@oscharko-dev/keiko-quality-intelligence 0.2.0

package/dist/ingestion/sourceMixPlanning.js

@@ -0,0 +1,65 @@
+// Quality Intelligence — source-mix planning (Epic #270, Issue #278).
+//
+// Deterministic planner that takes a list of `QualityIntelligenceSourceEnvelope`s and
+// returns a `SourceMixPlan`: a dedup'd, priority-ordered list of envelope ids together
+// with an oversize-flag table the consumer uses to decide what to skip.
+//
+// Pure: no IO, no clock, no randomness. Operates only on contract types from
+// @oscharko-dev/keiko-contracts.
+//
+// Structurally inspired by Test Intelligence reference (TI) source-mix planning, but the
+// envelope-ref shape and the priority table are anchored on the Keiko contracts surface.
+/** Per-kind priority weight: lower number = higher priority (planned earlier). */
+export const SOURCE_KIND_PRIORITY = {
+    "repository-context": 0,
+    "local-knowledge-capsule": 1,
+    "human-context": 2,
+    "figma-evidence": 3,
+    "connector-document": 4,
+};
+const DEFAULT_MAX_LABEL_BYTES = 256;
+const utf8ByteLength = (value) => new TextEncoder().encode(value).length;
+const stableSecondaryKey = (envelope) => `${envelope.kind}\u0000${envelope.id}`;
+const compareEntries = (a, b) => {
+    if (a.priority !== b.priority)
+        return a.priority - b.priority;
+    const ka = `${a.kind}\u0000${a.envelopeId}`;
+    const kb = `${b.kind}\u0000${b.envelopeId}`;
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+};
+/**
+ * Build a deterministic plan from a list of envelopes. Stable, pure.
+ */
+export const planSourceMix = (envelopes, options = {}) => {
+    const maxLabelBytes = options.maxLabelBytes ?? DEFAULT_MAX_LABEL_BYTES;
+    const maxEnvelopes = options.maxEnvelopes ?? 256;
+    const seen = new Set();
+    const droppedForDuplicate = [];
+    const candidate = [];
+    for (const envelope of envelopes) {
+        const key = stableSecondaryKey(envelope);
+        if (seen.has(key)) {
+            droppedForDuplicate.push(envelope.id);
+            continue;
+        }
+        seen.add(key);
+        const oversize = utf8ByteLength(envelope.displayLabel) > maxLabelBytes;
+        candidate.push({
+            envelopeId: envelope.id,
+            kind: envelope.kind,
+            priority: SOURCE_KIND_PRIORITY[envelope.kind],
+            oversize,
+        });
+    }
+    const sorted = [...candidate].sort(compareEntries);
+    const kept = sorted.slice(0, maxEnvelopes);
+    const cappedTail = sorted.slice(maxEnvelopes);
+    const droppedForCap = cappedTail.map((e) => e.envelopeId);
+    const oversizeCount = kept.reduce((acc, e) => acc + (e.oversize ? 1 : 0), 0);
+    return {
+        entries: kept,
+        droppedForDuplicate,
+        droppedForCap,
+        oversizeCount,
+    };
+};

package/dist/ingestion/sourceReconciliation.d.ts

@@ -0,0 +1,39 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+type Envelope = QualityIntelligence.QualityIntelligenceSourceEnvelope;
+type EnvelopeId = QualityIntelligence.QualityIntelligenceSourceEnvelopeId;
+/** A logical group of envelopes (e.g. one Conversation Center thread, one repo scan). */
+export interface SourceGroup {
+    /** Stable label for the group; used as the provenance origin. */
+    readonly groupLabel: string;
+    readonly envelopes: readonly Envelope[];
+}
+export interface ProvenanceEntry {
+    readonly envelopeId: EnvelopeId;
+    /** First group label that contributed this envelope. */
+    readonly firstGroupLabel: string;
+    /** All distinct group labels that contributed this envelope (insertion-stable). */
+    readonly contributingGroupLabels: readonly string[];
+}
+export interface ReconciledSourceSet {
+    /** Distinct envelopes in encounter order across the input groups. */
+    readonly envelopes: readonly Envelope[];
+    /** One provenance entry per distinct envelope id. */
+    readonly provenance: readonly ProvenanceEntry[];
+    /** Envelope ids that appeared in more than one group. */
+    readonly duplicatedAcrossGroups: readonly EnvelopeId[];
+    /** Envelopes that were skipped because the same id appeared with mismatched kind. */
+    readonly conflictingEnvelopeIds: readonly EnvelopeId[];
+}
+/**
+ * Merge multiple envelope groups into a single non-overlapping set. Pure.
+ *
+ * Invariants:
+ *   * Order: first appearance wins (encounter order across groups, then within group).
+ *   * Conflict: same id with different kind = both contributors are recorded in
+ *     `conflictingEnvelopeIds` and neither appears in `envelopes`.
+ *   * Duplicate: same id with same kind = first envelope kept; later groups appear in
+ *     the provenance entry's `contributingGroupLabels`.
+ */
+export declare const reconcileSourceGroups: (groups: readonly SourceGroup[]) => ReconciledSourceSet;
+export {};
+//# sourceMappingURL=sourceReconciliation.d.ts.map

package/dist/ingestion/sourceReconciliation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceReconciliation.d.ts","sourceRoot":"","sources":["../../src/ingestion/sourceReconciliation.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,KAAK,QAAQ,GAAG,mBAAmB,CAAC,iCAAiC,CAAC;AACtE,KAAK,UAAU,GAAG,mBAAmB,CAAC,mCAAmC,CAAC;AAE1E,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,yDAAyD;IACzD,QAAQ,CAAC,sBAAsB,EAAE,SAAS,UAAU,EAAE,CAAC;IACvD,qFAAqF;IACrF,QAAQ,CAAC,sBAAsB,EAAE,SAAS,UAAU,EAAE,CAAC;CACxD;AA8BD;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,SAAS,WAAW,EAAE,KAAG,mBAuCtE,CAAC"}

package/dist/ingestion/sourceReconciliation.js

@@ -0,0 +1,74 @@
+// Quality Intelligence — source reconciliation (Epic #270, Issue #278).
+//
+// Deterministic merge of multiple envelope groups (e.g. requirements + Figma + repo
+// context) into a single non-overlapping `ReconciledSourceSet` with provenance preserved
+// per envelope id.
+//
+// Pure: no IO, no clock, no randomness. Operates only on contract types from
+// @oscharko-dev/keiko-contracts.
+//
+// Structurally inspired by Test Intelligence reference (TI) source-reconciliation
+// patterns, but the provenance shape is anchored on the Keiko contracts surface.
+const indexEnvelope = (envelope, groupLabel, byId, provById, conflicts, duplicates) => {
+    const existing = byId.get(envelope.id);
+    if (existing === undefined) {
+        byId.set(envelope.id, envelope);
+        provById.set(envelope.id, {
+            firstGroupLabel: groupLabel,
+            contributingGroupLabels: [groupLabel],
+        });
+        return;
+    }
+    if (existing.kind !== envelope.kind) {
+        conflicts.add(envelope.id);
+        return;
+    }
+    duplicates.add(envelope.id);
+    const prov = provById.get(envelope.id);
+    if (prov !== undefined && !prov.contributingGroupLabels.includes(groupLabel)) {
+        prov.contributingGroupLabels.push(groupLabel);
+    }
+};
+/**
+ * Merge multiple envelope groups into a single non-overlapping set. Pure.
+ *
+ * Invariants:
+ *   * Order: first appearance wins (encounter order across groups, then within group).
+ *   * Conflict: same id with different kind = both contributors are recorded in
+ *     `conflictingEnvelopeIds` and neither appears in `envelopes`.
+ *   * Duplicate: same id with same kind = first envelope kept; later groups appear in
+ *     the provenance entry's `contributingGroupLabels`.
+ */
+export const reconcileSourceGroups = (groups) => {
+    const byId = new Map();
+    const provById = new Map();
+    const conflicts = new Set();
+    const duplicates = new Set();
+    for (const group of groups) {
+        for (const envelope of group.envelopes) {
+            indexEnvelope(envelope, group.groupLabel, byId, provById, conflicts, duplicates);
+        }
+    }
+    for (const id of conflicts) {
+        byId.delete(id);
+        provById.delete(id);
+        duplicates.delete(id);
+    }
+    const envelopes = [];
+    const provenance = [];
+    for (const [id, envelope] of byId) {
+        const prov = provById.get(id);
+        envelopes.push(envelope);
+        provenance.push({
+            envelopeId: id,
+            firstGroupLabel: prov?.firstGroupLabel ?? "",
+            contributingGroupLabels: prov?.contributingGroupLabels ?? [],
+        });
+    }
+    return {
+        envelopes,
+        provenance,
+        duplicatedAcrossGroups: [...duplicates],
+        conflictingEnvelopeIds: [...conflicts],
+    };
+};

package/dist/ingestion/untrustedContentNormalisation.d.ts

@@ -0,0 +1,23 @@
+/** Options governing clamp behaviour. */
+export interface NormaliseUntrustedContentOptions {
+    /** Maximum UTF-8 byte length to retain. Defaults to 64 KiB. */
+    readonly maxBytes?: number;
+}
+export interface NormaliseUntrustedContentResult {
+    readonly value: string;
+    readonly clamped: boolean;
+    readonly normalisedFromControlChars: boolean;
+    readonly markdownInjectionEscapes: number;
+}
+/**
+ * Normalise an untrusted free-text payload:
+ *   1. NFKC normalise.
+ *   2. Strip C0/C1/DEL control characters (keeping TAB/LF/CR text whitespace).
+ *   3. Escape Markdown-injection vectors (heading, fenced code, image, link).
+ *   4. Clamp to `maxBytes` UTF-8 bytes (default 64 KiB).
+ *
+ * Pure: no IO, no clock, no randomness.
+ */
+export declare const normaliseUntrustedContent: (raw: string, options?: NormaliseUntrustedContentOptions) => NormaliseUntrustedContentResult;
+export declare const UNTRUSTED_CONTENT_DEFAULT_MAX_BYTES: number;
+//# sourceMappingURL=untrustedContentNormalisation.d.ts.map

package/dist/ingestion/untrustedContentNormalisation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrustedContentNormalisation.d.ts","sourceRoot":"","sources":["../../src/ingestion/untrustedContentNormalisation.ts"],"names":[],"mappings":"AAgBA,yCAAyC;AACzC,MAAM,WAAW,gCAAgC;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;CAC3C;AA2FD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GACpC,KAAK,MAAM,EACX,UAAS,gCAAqC,KAC7C,+BAYF,CAAC;AAEF,eAAO,MAAM,mCAAmC,QAAoB,CAAC"}

package/dist/ingestion/untrustedContentNormalisation.js

@@ -0,0 +1,121 @@
+// Quality Intelligence — untrusted content normalisation (Epic #270, Issue #278).
+//
+// Pure deterministic primitives that prepare free-text payloads (Figma node text,
+// connector document snippets, human-context strings) for safe transit through the
+// QI evidence-atom + envelope contracts. No IO. No network. No `node:fs`. No clock
+// reads. No randomness. The functions never throw on inputs they choose to clamp —
+// callers may layer a typed error on top.
+//
+// Structurally inspired by Test Intelligence reference (TI) multi-source text
+// normalisation pipelines, but rewritten to consume the Keiko contracts surface and
+// match the audit-ledger's NFKC + control-char rules already encoded in
+// `validateQualityIntelligenceIdString` (@oscharko-dev/keiko-contracts, ids.ts).
+const DEFAULT_MAX_BYTES = 64 * 1024;
+const CLAMP_SUFFIX = "…";
+// Markdown-injection vectors we escape (not strip) so the audit ledger retains the
+// surrounding text. Escape with a leading backslash; the rendered text is byte-stable.
+const HEADING_LINE = /^(#{1,6})/gmu;
+const FENCED_CODE = /```/gu;
+const IMAGE_OPEN = /!\[/gu;
+const LINK_OPEN = /(?<!!)\[([^\]]*)\]\(/gu;
+const isControlCodePoint = (code) => {
+    // TAB (0x09), LF (0x0A), and CR (0x0D) are C0 code points but are legitimate
+    // text whitespace: stripping them would collapse multi-line content (e.g. a
+    // code block or a multi-line document excerpt) into a single run-on line. They
+    // must survive normalisation. This mirrors the prompt-boundary scrubber and the
+    // single-file binary guard (keiko-server isControlChar), so every layer treats
+    // the same code points as text.
+    if (code === 0x09 || code === 0x0a || code === 0x0d)
+        return false;
+    // C0 controls 0x00–0x1F, DEL 0x7F, C1 controls 0x80–0x9F.
+    if (code <= 0x1f)
+        return true;
+    if (code === 0x7f)
+        return true;
+    if (code >= 0x80 && code <= 0x9f)
+        return true;
+    return false;
+};
+const stripControlCharacters = (value) => {
+    let out = "";
+    let stripped = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (isControlCodePoint(code)) {
+            stripped = true;
+            continue;
+        }
+        out += value.charAt(i);
+    }
+    return { value: out, stripped };
+};
+const escapeMarkdownInjection = (value) => {
+    let count = 0;
+    const headingEscaped = value.replace(HEADING_LINE, (hashes) => {
+        count += 1;
+        return `\\${hashes}`;
+    });
+    const codeEscaped = headingEscaped.replace(FENCED_CODE, () => {
+        count += 1;
+        return "\\`\\`\\`";
+    });
+    const imageEscaped = codeEscaped.replace(IMAGE_OPEN, () => {
+        count += 1;
+        return "\\!\\[";
+    });
+    const linkEscaped = imageEscaped.replace(LINK_OPEN, (_match, inner) => {
+        count += 1;
+        return `\\[${inner}\\](`;
+    });
+    return { value: linkEscaped, count };
+};
+const clampToBytes = (value, maxBytes) => {
+    if (maxBytes <= 0) {
+        return { value: "", clamped: value.length > 0 };
+    }
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(value);
+    if (bytes.length <= maxBytes) {
+        return { value, clamped: false };
+    }
+    let truncatedBytes = bytes.slice(0, maxBytes);
+    // Trim trailing partial UTF-8 sequence (continuation bytes 0x80–0xBF without a starter).
+    while (truncatedBytes.length > 0) {
+        const last = truncatedBytes[truncatedBytes.length - 1] ?? 0;
+        if ((last & 0xc0) === 0x80) {
+            truncatedBytes = truncatedBytes.slice(0, -1);
+        }
+        else {
+            // If this is itself a multi-byte starter (>= 0xC0), drop it too: it has no continuation.
+            if (last >= 0xc0) {
+                truncatedBytes = truncatedBytes.slice(0, -1);
+            }
+            break;
+        }
+    }
+    const decoder = new TextDecoder("utf-8", { fatal: false });
+    return { value: `${decoder.decode(truncatedBytes)}${CLAMP_SUFFIX}`, clamped: true };
+};
+/**
+ * Normalise an untrusted free-text payload:
+ *   1. NFKC normalise.
+ *   2. Strip C0/C1/DEL control characters (keeping TAB/LF/CR text whitespace).
+ *   3. Escape Markdown-injection vectors (heading, fenced code, image, link).
+ *   4. Clamp to `maxBytes` UTF-8 bytes (default 64 KiB).
+ *
+ * Pure: no IO, no clock, no randomness.
+ */
+export const normaliseUntrustedContent = (raw, options = {}) => {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const normalised = raw.normalize("NFKC");
+    const stripped = stripControlCharacters(normalised);
+    const escaped = escapeMarkdownInjection(stripped.value);
+    const clamped = clampToBytes(escaped.value, maxBytes);
+    return {
+        value: clamped.value,
+        clamped: clamped.clamped,
+        normalisedFromControlChars: stripped.stripped,
+        markdownInjectionEscapes: escaped.count,
+    };
+};
+export const UNTRUSTED_CONTENT_DEFAULT_MAX_BYTES = DEFAULT_MAX_BYTES;

package/dist/ingestion/workspaceAdapter.d.ts

@@ -0,0 +1,55 @@
+import type { ContextPack } from "@oscharko-dev/keiko-contracts";
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { type SourceMixPlan } from "./sourceMixPlanning.js";
+type RepoEnvelope = QualityIntelligence.QualityIntelligenceRepositoryContextEnvelope;
+export type WorkspaceAdapterErrorCode = "ABSOLUTE_PATH" | "PATH_TRAVERSAL" | "EMPTY_PATH" | "INVALID_INTEGRITY_HASH" | "INVALID_REGISTERED_AT";
+export declare class WorkspaceAdapterError extends Error {
+    readonly code: WorkspaceAdapterErrorCode;
+    constructor(code: WorkspaceAdapterErrorCode, message: string);
+}
+export interface BuildWorkspaceEnvelopesInput {
+    /**
+     * Display-only label naming the workspace (e.g. "main", "feature/foo"). Not a path,
+     * not a URL; carried only into envelope `displayLabel` and `provenance.origin`.
+     */
+    readonly workspaceLabel: string;
+    /**
+     * ISO 8601 UTC timestamp the consumer captured when assembling the pack. The QI
+     * ingestion sub-namespace deliberately refuses to read the clock so callers stay
+     * deterministic.
+     */
+    readonly registeredAt: string;
+    readonly contextPack: ContextPack;
+    /**
+     * Caller-supplied SHA-256 hex digest table keyed by the context-entry path. The
+     * adapter rejects any entry without a matching digest with `INVALID_INTEGRITY_HASH`.
+     */
+    readonly integrityHashByEntryPath: Readonly<Record<string, string>>;
+    /**
+     * Optional id-prefix the caller pre-allocates (e.g. "qi-src-ws-1234"). Each envelope's
+     * id is `${idPrefix}:${entry.path}`; the contract validator (asQualityIntelligence-
+     * SourceEnvelopeId) rejects forbidden fragments — callers must pre-validate the
+     * prefix.
+     */
+    readonly idPrefix: string;
+}
+/**
+ * Convert a workspace `ContextPack` into a list of repository-context source envelopes,
+ * one per context entry. Pure, no IO.
+ *
+ * Rejects:
+ *   * absolute paths or paths containing `..` segments
+ *   * missing or non-hex-64 integrity hashes
+ *   * malformed `registeredAt` timestamps
+ */
+export declare const buildWorkspaceSourceEnvelopes: (input: BuildWorkspaceEnvelopesInput) => readonly RepoEnvelope[];
+/**
+ * Convenience: build envelopes AND run the deterministic mix planner so the consumer
+ * gets the policy-ordered planner output in a single call. Pure.
+ */
+export declare const workspaceSourceMixPolicy: (input: BuildWorkspaceEnvelopesInput) => {
+    readonly envelopes: readonly RepoEnvelope[];
+    readonly plan: SourceMixPlan;
+};
+export {};
+//# sourceMappingURL=workspaceAdapter.d.ts.map

package/dist/ingestion/workspaceAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceAdapter.d.ts","sourceRoot":"","sources":["../../src/ingestion/workspaceAdapter.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE3E,KAAK,YAAY,GAAG,mBAAmB,CAAC,4CAA4C,CAAC;AAGrF,MAAM,MAAM,yBAAyB,GACjC,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,wBAAwB,GACxB,uBAAuB,CAAC;AAE5B,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,yBAAyB,CAAC;gBACpC,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM;CAK7D;AAyDD,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACxC,OAAO,4BAA4B,KAClC,SAAS,YAAY,EA2BvB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,4BAA4B,KAClC;IACD,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAK9B,CAAC"}

package/dist/ingestion/workspaceAdapter.js

@@ -0,0 +1,113 @@
+// Quality Intelligence — Workspace adapter (Epic #270, Issue #278).
+//
+// Pure adapter that converts a `ContextPack` from @oscharko-dev/keiko-workspace into a
+// `QualityIntelligenceRepositoryContextEnvelope` (kind: "repository-context") suitable
+// for QI ingestion. The QI pure-domain package is locked down (ADR-0019 rule 10a) to
+// `keiko-contracts` and `keiko-security` only, so this adapter consumes the workspace
+// contract types via their re-export from @oscharko-dev/keiko-contracts (workspace.ts).
+//
+// Why this is safe:
+//   * Path containment stays in @oscharko-dev/keiko-workspace at construction time.
+//   * The adapter accepts only the already-redacted `ContextPack` and carries only
+//     workspace-relative refs into the envelope. Absolute paths and `..` segments are
+//     rejected with a typed `WorkspaceAdapterError` so a caller cannot smuggle an
+//     out-of-workspace ref through the contract surface.
+//   * The envelope `integrityHashSha256Hex` is computed by the caller (the workspace
+//     adapter declines to import @oscharko-dev/keiko-security to avoid pulling a hashing
+//     primitive into the QI ingestion sub-namespace; callers compute the digest in the
+//     keiko-workspace consumer and pass it in).
+//
+// Structurally inspired by Test Intelligence reference (TI) repo-context adapters, but
+// the envelope shape is anchored on the QI contracts.
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { planSourceMix } from "./sourceMixPlanning.js";
+const { asQualityIntelligenceSourceEnvelopeId } = QualityIntelligence;
+export class WorkspaceAdapterError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.name = "WorkspaceAdapterError";
+        this.code = code;
+    }
+}
+const HEX64 = /^[0-9a-f]{64}$/u;
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/u;
+const assertRelativePath = (path) => {
+    if (path.length === 0) {
+        throw new WorkspaceAdapterError("EMPTY_PATH", "Context entry path is empty");
+    }
+    // Absolute path on POSIX or Windows drive-style ("C:\…" / "C:/…").
+    if (path.startsWith("/") || /^[A-Za-z]:[\\/]/u.test(path)) {
+        throw new WorkspaceAdapterError("ABSOLUTE_PATH", `Context entry path must be workspace-relative; got "${path}"`);
+    }
+    // Reject any `..` segment regardless of separator.
+    const segments = path.split(/[\\/]/u);
+    if (segments.some((s) => s === "..")) {
+        throw new WorkspaceAdapterError("PATH_TRAVERSAL", `Context entry path contains a ".." segment: "${path}"`);
+    }
+};
+const assertHash = (hash) => {
+    if (!HEX64.test(hash)) {
+        throw new WorkspaceAdapterError("INVALID_INTEGRITY_HASH", "integrityHashSha256Hex must be 64 lowercase hex chars");
+    }
+};
+const assertRegisteredAt = (timestamp) => {
+    if (!ISO_8601.test(timestamp)) {
+        throw new WorkspaceAdapterError("INVALID_REGISTERED_AT", "registeredAt must be ISO 8601 UTC (e.g. 2026-06-05T00:00:00Z)");
+    }
+};
+const buildLocalRef = (entry) => {
+    assertRelativePath(entry.path);
+    return entry.path;
+};
+const buildDisplayLabel = (rootLabel, entry) => {
+    const base = `${rootLabel}:${entry.path}`;
+    // The envelope itself caps display labels at 256; we trim here so the consumer
+    // never has to discard an otherwise valid envelope.
+    if (base.length <= 256)
+        return base;
+    return `${base.slice(0, 253)}...`;
+};
+/**
+ * Convert a workspace `ContextPack` into a list of repository-context source envelopes,
+ * one per context entry. Pure, no IO.
+ *
+ * Rejects:
+ *   * absolute paths or paths containing `..` segments
+ *   * missing or non-hex-64 integrity hashes
+ *   * malformed `registeredAt` timestamps
+ */
+export const buildWorkspaceSourceEnvelopes = (input) => {
+    assertRegisteredAt(input.registeredAt);
+    const envelopes = [];
+    for (const entry of input.contextPack.selected) {
+        const localRef = buildLocalRef(entry);
+        const hash = input.integrityHashByEntryPath[entry.path];
+        if (typeof hash !== "string") {
+            throw new WorkspaceAdapterError("INVALID_INTEGRITY_HASH", `No integrity hash supplied for entry "${entry.path}"`);
+        }
+        assertHash(hash);
+        const id = asQualityIntelligenceSourceEnvelopeId(`${input.idPrefix}:${entry.path}`);
+        envelopes.push({
+            id,
+            kind: "repository-context",
+            displayLabel: buildDisplayLabel(input.workspaceLabel, entry),
+            provenance: {
+                origin: `workspace:${input.workspaceLabel}`,
+                registeredAt: input.registeredAt,
+                integrityHashSha256Hex: hash,
+            },
+            localRef,
+        });
+    }
+    return envelopes;
+};
+/**
+ * Convenience: build envelopes AND run the deterministic mix planner so the consumer
+ * gets the policy-ordered planner output in a single call. Pure.
+ */
+export const workspaceSourceMixPolicy = (input) => {
+    const envelopes = buildWorkspaceSourceEnvelopes(input);
+    const plan = planSourceMix(envelopes);
+    return { envelopes, plan };
+};

package/dist/review/auditEvents.d.ts

@@ -0,0 +1,61 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import type { NextReviewState, QualityIntelligenceReviewTransitionEvent } from "./stateMachine.js";
+export declare const QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_SCHEMA_VERSION: 1;
+export type QualityIntelligenceReviewAuditEventKind = "qi:review:opened" | "qi:review:transitioned" | "qi:review:four-eyes-paired" | "qi:review:terminated";
+export declare const QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_KINDS: readonly QualityIntelligenceReviewAuditEventKind[];
+export interface QualityIntelligenceReviewOpenedPayload {
+    readonly kind: "qi:review:opened";
+    readonly reviewerKind: QualityIntelligence.QualityIntelligenceReviewerKind;
+}
+export interface QualityIntelligenceReviewTransitionedPayload {
+    readonly kind: "qi:review:transitioned";
+    readonly from: QualityIntelligence.QualityIntelligenceReviewState;
+    readonly to: QualityIntelligence.QualityIntelligenceReviewState;
+    readonly event: QualityIntelligenceReviewTransitionEvent;
+}
+export interface QualityIntelligenceReviewFourEyesPairedPayload {
+    readonly kind: "qi:review:four-eyes-paired";
+    readonly pairedRecordId: QualityIntelligence.QualityIntelligenceReviewRecordId;
+}
+export interface QualityIntelligenceReviewTerminatedPayload {
+    readonly kind: "qi:review:terminated";
+    readonly terminalState: QualityIntelligence.QualityIntelligenceReviewState;
+}
+export type QualityIntelligenceReviewAuditEventPayload = QualityIntelligenceReviewOpenedPayload | QualityIntelligenceReviewTransitionedPayload | QualityIntelligenceReviewFourEyesPairedPayload | QualityIntelligenceReviewTerminatedPayload;
+export interface QualityIntelligenceReviewAuditEvent {
+    readonly eventSchemaVersion: typeof QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_SCHEMA_VERSION;
+    readonly runId: QualityIntelligence.QualityIntelligenceRunId;
+    readonly recordId: QualityIntelligence.QualityIntelligenceReviewRecordId;
+    /** Monotonic per-run non-negative integer. Assigned by the runtime. */
+    readonly sequence: number;
+    /** ISO 8601 timestamp supplied by the caller. */
+    readonly timestamp: string;
+    /** Display-only actor label. NO PII guarantee — same rule as reviewerLabel. */
+    readonly by: string;
+    readonly payload: QualityIntelligenceReviewAuditEventPayload;
+}
+export interface BuildReviewAuditEventInput {
+    readonly runId: QualityIntelligence.QualityIntelligenceRunId;
+    readonly recordId: QualityIntelligence.QualityIntelligenceReviewRecordId;
+    readonly sequence: number;
+    readonly timestamp: string;
+    readonly by: string;
+    readonly payload: QualityIntelligenceReviewAuditEventPayload;
+}
+/**
+ * Build a frozen audit-event envelope. Pure: does not consult any clock, does
+ * not allocate beyond the returned envelope, does not validate `timestamp`
+ * beyond presence. The runtime (#273) assigns `sequence` in observed order;
+ * callers should pass the next integer for the run.
+ *
+ * Throws `RangeError` if `sequence` is not a non-negative integer — this is
+ * the same guarantee as `assertRunEventSequenceMonotonic`.
+ */
+export declare const buildReviewAuditEvent: (input: BuildReviewAuditEventInput) => QualityIntelligenceReviewAuditEvent;
+/**
+ * Convenience derivation: build the `qi:review:transitioned` payload from a
+ * `NextReviewState` produced by `applyReviewTransition`. Exposed so the
+ * runtime can compose the two pure functions without re-deriving fields.
+ */
+export declare const transitionedPayloadFromNext: (next: NextReviewState) => QualityIntelligenceReviewTransitionedPayload;
+//# sourceMappingURL=auditEvents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auditEvents.d.ts","sourceRoot":"","sources":["../../src/review/auditEvents.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,wCAAwC,EAAE,MAAM,mBAAmB,CAAC;AAEnG,eAAO,MAAM,sDAAsD,EAAG,CAAU,CAAC;AAEjF,MAAM,MAAM,uCAAuC,GAC/C,kBAAkB,GAClB,wBAAwB,GACxB,4BAA4B,GAC5B,sBAAsB,CAAC;AAE3B,eAAO,MAAM,6CAA6C,EAAE,SAAS,uCAAuC,EAMhG,CAAC;AAEb,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC,+BAA+B,CAAC;CAC5E;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC,8BAA8B,CAAC;IAClE,QAAQ,CAAC,EAAE,EAAE,mBAAmB,CAAC,8BAA8B,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,wCAAwC,CAAC;CAC1D;AAED,MAAM,WAAW,8CAA8C;IAC7D,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,mBAAmB,CAAC,iCAAiC,CAAC;CAChF;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC,8BAA8B,CAAC;CAC5E;AAED,MAAM,MAAM,0CAA0C,GAClD,sCAAsC,GACtC,4CAA4C,GAC5C,8CAA8C,GAC9C,0CAA0C,CAAC;AAE/C,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,kBAAkB,EAAE,OAAO,sDAAsD,CAAC;IAC3F,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC,wBAAwB,CAAC;IAC7D,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,iCAAiC,CAAC;IACzE,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,0CAA0C,CAAC;CAC9D;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC,wBAAwB,CAAC;IAC7D,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,iCAAiC,CAAC;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,0CAA0C,CAAC;CAC9D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,0BAA0B,KAChC,mCAeF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GACtC,MAAM,eAAe,KACpB,4CAMC,CAAC"}

package/dist/review/auditEvents.js

@@ -0,0 +1,50 @@
+// Quality Intelligence review audit-event producer (Epic #270, Issue #282).
+//
+// Pure-domain envelope builder. Emits versioned audit events for the review
+// lifecycle. PRODUCTION ONLY — persistence belongs to keiko-evidence (#274)
+// and the audit ledger. No IO, no clock, no allocations beyond the returned
+// frozen envelope.
+//
+// Schema-version policy mirrors QUALITY_INTELLIGENCE_EVENT_SCHEMA_VERSION:
+// future evolutions land as new numeric literals, never as a mutation of "1".
+export const QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_SCHEMA_VERSION = 1;
+export const QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_KINDS = [
+    "qi:review:opened",
+    "qi:review:transitioned",
+    "qi:review:four-eyes-paired",
+    "qi:review:terminated",
+];
+/**
+ * Build a frozen audit-event envelope. Pure: does not consult any clock, does
+ * not allocate beyond the returned envelope, does not validate `timestamp`
+ * beyond presence. The runtime (#273) assigns `sequence` in observed order;
+ * callers should pass the next integer for the run.
+ *
+ * Throws `RangeError` if `sequence` is not a non-negative integer — this is
+ * the same guarantee as `assertRunEventSequenceMonotonic`.
+ */
+export const buildReviewAuditEvent = (input) => {
+    if (!Number.isInteger(input.sequence) || input.sequence < 0) {
+        throw new RangeError(`Review audit event sequence must be a non-negative integer, got ${String(input.sequence)}`);
+    }
+    return Object.freeze({
+        eventSchemaVersion: QUALITY_INTELLIGENCE_REVIEW_AUDIT_EVENT_SCHEMA_VERSION,
+        runId: input.runId,
+        recordId: input.recordId,
+        sequence: input.sequence,
+        timestamp: input.timestamp,
+        by: input.by,
+        payload: input.payload,
+    });
+};
+/**
+ * Convenience derivation: build the `qi:review:transitioned` payload from a
+ * `NextReviewState` produced by `applyReviewTransition`. Exposed so the
+ * runtime can compose the two pure functions without re-deriving fields.
+ */
+export const transitionedPayloadFromNext = (next) => Object.freeze({
+    kind: "qi:review:transitioned",
+    from: next.from,
+    to: next.state,
+    event: next.event,
+});

package/dist/review/fourEyes.d.ts

@@ -0,0 +1,24 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+export type QualityIntelligenceFourEyesViolationCode = "SELF_REVIEW_FORBIDDEN" | "SAME_REVIEWER_LABEL" | "ALREADY_PAIRED";
+export declare class QualityIntelligenceFourEyesViolationError extends Error {
+    readonly code: QualityIntelligenceFourEyesViolationCode;
+    readonly recordId: QualityIntelligence.QualityIntelligenceReviewRecordId;
+    readonly candidateId: QualityIntelligence.QualityIntelligenceReviewRecordId;
+    constructor(code: QualityIntelligenceFourEyesViolationCode, record: QualityIntelligence.QualityIntelligenceReviewRecord, candidate: QualityIntelligence.QualityIntelligenceReviewRecord, detail: string);
+}
+/**
+ * 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 declare const assertFourEyesPair: (record: QualityIntelligence.QualityIntelligenceReviewRecord, candidate: QualityIntelligence.QualityIntelligenceReviewRecord) => void;
+//# sourceMappingURL=fourEyes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fourEyes.d.ts","sourceRoot":"","sources":["../../src/review/fourEyes.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,MAAM,MAAM,wCAAwC,GAChD,uBAAuB,GACvB,qBAAqB,GACrB,gBAAgB,CAAC;AAErB,qBAAa,yCAA0C,SAAQ,KAAK;IAClE,SAAgB,IAAI,EAAE,wCAAwC,CAAC;IAC/D,SAAgB,QAAQ,EAAE,mBAAmB,CAAC,iCAAiC,CAAC;IAChF,SAAgB,WAAW,EAAE,mBAAmB,CAAC,iCAAiC,CAAC;gBAGjF,IAAI,EAAE,wCAAwC,EAC9C,MAAM,EAAE,mBAAmB,CAAC,+BAA+B,EAC3D,SAAS,EAAE,mBAAmB,CAAC,+BAA+B,EAC9D,MAAM,EAAE,MAAM;CAQjB;AAID;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,mBAAmB,CAAC,+BAA+B,EAC3D,WAAW,mBAAmB,CAAC,+BAA+B,KAC7D,IA4BF,CAAC"}