@oscharko-dev/keiko-quality-intelligence 0.2.0

package/dist/hardening/pathSafety.js

@@ -0,0 +1,61 @@
+// Quality Intelligence — path-safety predicates (Epic #270, Issue #284).
+//
+// Pure synchronous predicates that reject obviously-dangerous relative paths
+// BEFORE they cross any IO seam (Workspace, Evidence, Connector). The package
+// itself performs no IO; these helpers exist so adjacent leaves can reject
+// adversarial inputs at the contract boundary with byte-stable, cross-platform
+// semantics. No `node:path` import: rule is intentionally `path.sep`-agnostic
+// so the same predicate accepts/rejects identical strings on POSIX and Windows.
+//
+// Structurally inspired by Test Intelligence reference (TI) path-guard rules,
+// rewritten against the Keiko contracts surface.
+/** Maximum permitted UTF-16 length of a safe relative path. */
+export const MAX_SAFE_RELATIVE_PATH_LENGTH = 256;
+const FORBIDDEN_DOTDOT_SEGMENT = /(^|[\\/])\.\.([\\/]|$)/u;
+const containsControlOrNullByte = (value) => {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        // C0 control range (includes NUL 0x00), DEL, and C1 control range.
+        if (code <= 0x1f)
+            return true;
+        if (code === 0x7f)
+            return true;
+        if (code >= 0x80 && code <= 0x9f)
+            return true;
+    }
+    return false;
+};
+/**
+ * Predicate: returns `true` when the supplied string is a syntactically safe
+ * relative path acceptable for use as a contract field (Quality Intelligence
+ * evidence reference, source-mix planning key, etc.).
+ *
+ * Rejects when ANY of the following hold:
+ *   - empty string
+ *   - contains a `..` path segment (POSIX or Windows separator)
+ *   - contains a null byte or any C0/DEL control char
+ *   - starts with `/` (POSIX absolute) or `\` (Windows root)
+ *   - contains `:` (Windows drive letter, NTFS ADS, scheme prefix)
+ *   - exceeds {@link MAX_SAFE_RELATIVE_PATH_LENGTH} UTF-16 code units
+ *
+ * Pure: no IO, no clock, no randomness, no `node:path`.
+ */
+export const isSafeRelativePath = (candidate) => {
+    if (typeof candidate !== "string")
+        return false;
+    if (candidate.length === 0)
+        return false;
+    if (candidate.length > MAX_SAFE_RELATIVE_PATH_LENGTH)
+        return false;
+    if (candidate.startsWith("/"))
+        return false;
+    if (candidate.startsWith("\\"))
+        return false;
+    if (candidate.includes(":"))
+        return false;
+    if (containsControlOrNullByte(candidate))
+        return false;
+    if (FORBIDDEN_DOTDOT_SEGMENT.test(candidate))
+        return false;
+    return true;
+};

package/dist/hardening/promptInjectionScrub.d.ts

@@ -0,0 +1,17 @@
+export interface PromptInjectionScanResult {
+    readonly safe: boolean;
+    readonly injections: readonly string[];
+}
+/** Number of patterns in the injection corpus. Useful for tests/diagnostics. */
+export declare const PROMPT_INJECTION_PATTERN_COUNT: number;
+/**
+ * Scan an untrusted text payload for known prompt-injection vectors.
+ *
+ * Returns `{ safe: true, injections: [] }` when no pattern matches, or
+ * `{ safe: false, injections }` with the names of the matched patterns. The
+ * caller decides whether to redact, quarantine, or fail-closed.
+ *
+ * Pure: no IO, no clock, no randomness.
+ */
+export declare const scanForPromptInjections: (input: string) => PromptInjectionScanResult;
+//# sourceMappingURL=promptInjectionScrub.d.ts.map

package/dist/hardening/promptInjectionScrub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptInjectionScrub.d.ts","sourceRoot":"","sources":["../../src/hardening/promptInjectionScrub.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AA2CD,gFAAgF;AAChF,eAAO,MAAM,8BAA8B,QAAmC,CAAC;AAE/E;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAO,MAAM,KAAG,yBAWvD,CAAC"}

package/dist/hardening/promptInjectionScrub.js

@@ -0,0 +1,72 @@
+// Quality Intelligence — prompt-injection scrubber (Epic #270, Issue #284).
+//
+// Pure detection of prompt-injection vectors that survive
+// `normaliseUntrustedContent` (Issue #278). The scrubber returns the list of
+// matched patterns instead of mutating the text, so callers may quarantine the
+// snippet, redact it, or fail-closed. The injection patterns are layered as a
+// second line of defence behind the Markdown escapes in #278 — they aim at
+// natural-language imperatives that markdown escaping does NOT touch.
+//
+// Pure: no IO, no clock, no randomness. Matching is case-insensitive over the
+// NFKC-normalised + control-stripped form of the input — callers SHOULD run
+// `normaliseUntrustedContent` first so the patterns see the canonical form.
+//
+// Structurally inspired by Test Intelligence reference (TI) prompt-injection
+// detectors, rewritten against the Keiko contracts surface.
+const PROMPT_INJECTION_PATTERNS = [
+    {
+        name: "ignore-previous-instructions",
+        pattern: /ignore (?:all |the )?previous instructions?/iu,
+    },
+    {
+        name: "disregard-previous-instructions",
+        pattern: /disregard (?:all |the )?(?:previous|above) instructions?/iu,
+    },
+    { name: "override-system-prompt", pattern: /(?:override|bypass) (?:the )?system prompt/iu },
+    { name: "system-role-injection", pattern: /(^|[\n\r])\s*system\s*:/iu },
+    { name: "assistant-role-injection", pattern: /(^|[\n\r])\s*assistant\s*:/iu },
+    { name: "developer-role-injection", pattern: /(^|[\n\r])\s*developer\s*:/iu },
+    { name: "im-start-token", pattern: /<\|im_start\|>/iu },
+    { name: "im-end-token", pattern: /<\|im_end\|>/iu },
+    { name: "endoftext-token", pattern: /<\|endoftext\|>/iu },
+    { name: "markdown-system-heading", pattern: /(^|\n)#{1,6}\s*system\b/iu },
+    {
+        name: "you-are-now-jailbreak",
+        pattern: /you are (?:now )?(?:a |an )?(?:dan|jailbroken|unrestricted)/iu,
+    },
+    {
+        name: "act-as-different-model",
+        pattern: /act as (?:a |an )?(?:different|new) (?:ai|model|assistant)/iu,
+    },
+    {
+        name: "reveal-system-prompt",
+        pattern: /(?:reveal|print|show|output) (?:the |your )?system prompt/iu,
+    },
+    {
+        name: "exfiltrate-secrets",
+        pattern: /(?:reveal|print|show|leak|exfiltrate) (?:the |your |any )?(?:api[\s-]?key|secret|password|token)s?/iu,
+    },
+];
+/** Number of patterns in the injection corpus. Useful for tests/diagnostics. */
+export const PROMPT_INJECTION_PATTERN_COUNT = PROMPT_INJECTION_PATTERNS.length;
+/**
+ * Scan an untrusted text payload for known prompt-injection vectors.
+ *
+ * Returns `{ safe: true, injections: [] }` when no pattern matches, or
+ * `{ safe: false, injections }` with the names of the matched patterns. The
+ * caller decides whether to redact, quarantine, or fail-closed.
+ *
+ * Pure: no IO, no clock, no randomness.
+ */
+export const scanForPromptInjections = (input) => {
+    if (typeof input !== "string" || input.length === 0) {
+        return { safe: true, injections: [] };
+    }
+    const matched = [];
+    for (const { name, pattern } of PROMPT_INJECTION_PATTERNS) {
+        if (pattern.test(input)) {
+            matched.push(name);
+        }
+    }
+    return { safe: matched.length === 0, injections: matched };
+};

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { compareStaleness } from "./domain/staleness.js";
+export type { StalenessReason, StalenessResult } from "./domain/staleness.js";
+export { deriveIntent } from "./domain/intentDerivation.js";
+export type { IntentSummary } from "./domain/intentDerivation.js";
+export { designTestCaseCandidates, DETERMINISTIC_BASELINE_PROVENANCE_TAG, } from "./domain/testDesignModel.js";
+export type { DesignTestCaseCandidatesInput } from "./domain/testDesignModel.js";
+export { buildAtomCoverageStatuses, buildCoverageMap, classifyAtomCoverage, COVERAGE_THRESHOLD_COVERED, COVERAGE_THRESHOLD_WEAKLY_COVERED, runCoveragePercentage, } from "./domain/coverageRelevance.js";
+export type { AtomCoverageStatus, BuildCoverageMapInput, CoverageStatus, } from "./domain/coverageRelevance.js";
+export { buildRequirementExcerpt, REQUIREMENT_EXCERPT_MAX_CHARS, } from "./domain/requirementExcerpt.js";
+export { computeCandidateEquivalenceSignature, deduplicateCandidates, } from "./domain/deduplication.js";
+export { validateCandidates } from "./domain/validation.js";
+export { ALL_POLICY_PROFILES, bankingDefault, insuranceDefault, regressionDefault, } from "./domain/policyProfile.js";
+export type { PolicyProfile } from "./domain/policyProfile.js";
+export { canonicaliseFragmentList, isKnownPriority, isMeaningfulText, isUnsafeFormatCodePoint, normaliseCandidateText, normaliseText, stripUnsafeFormatChars, } from "./domain/assertions.js";
+export { TEST_QUALITY_WEAK_THRESHOLD, scoreFromDimensions, verdictFromDimensions, verdictFromScore, } from "./domain/testQualityRubric.js";
+export * as QualityIntelligenceIngestion from "./ingestion/index.js";
+export * as QualityIntelligenceReview from "./review/index.js";
+export * as QualityIntelligenceHardening from "./hardening/index.js";
+export * as QualityIntelligenceExport from "./export/index.js";
+export * as QualityIntelligenceGeneration from "./generation/index.js";
+export * as QualityIntelligenceFigma from "./domain/figma/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,EACL,wBAAwB,EACxB,qCAAqC,GACtC,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAEjF,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,GACf,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,oCAAoC,EACpC,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,KAAK,4BAA4B,MAAM,sBAAsB,CAAC;AAMrE,OAAO,KAAK,yBAAyB,MAAM,mBAAmB,CAAC;AAK/D,OAAO,KAAK,4BAA4B,MAAM,sBAAsB,CAAC;AAMrE,OAAO,KAAK,yBAAyB,MAAM,mBAAmB,CAAC;AAM/D,OAAO,KAAK,6BAA6B,MAAM,uBAAuB,CAAC;AAMvE,OAAO,KAAK,wBAAwB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,44 @@
+// Public barrel for @oscharko-dev/keiko-quality-intelligence (Epic #270, Issue #272).
+//
+// Pure-domain package: no IO, no provider SDK, no UI, no BFF, no scheduler, no event bus,
+// no direct model calls. Consumes contracts via the @oscharko-dev/keiko-contracts barrel
+// and redaction/hashing primitives via @oscharko-dev/keiko-security only.
+// ─── Staleness / drift detection (Epic #735, Issue #742) ──────────────────────
+export { compareStaleness } from "./domain/staleness.js";
+export { deriveIntent } from "./domain/intentDerivation.js";
+export { designTestCaseCandidates, DETERMINISTIC_BASELINE_PROVENANCE_TAG, } from "./domain/testDesignModel.js";
+export { buildAtomCoverageStatuses, buildCoverageMap, classifyAtomCoverage, COVERAGE_THRESHOLD_COVERED, COVERAGE_THRESHOLD_WEAKLY_COVERED, runCoveragePercentage, } from "./domain/coverageRelevance.js";
+export { buildRequirementExcerpt, REQUIREMENT_EXCERPT_MAX_CHARS, } from "./domain/requirementExcerpt.js";
+export { computeCandidateEquivalenceSignature, deduplicateCandidates, } from "./domain/deduplication.js";
+export { validateCandidates } from "./domain/validation.js";
+export { ALL_POLICY_PROFILES, bankingDefault, insuranceDefault, regressionDefault, } from "./domain/policyProfile.js";
+export { canonicaliseFragmentList, isKnownPriority, isMeaningfulText, isUnsafeFormatCodePoint, normaliseCandidateText, normaliseText, stripUnsafeFormatChars, } from "./domain/assertions.js";
+export { TEST_QUALITY_WEAK_THRESHOLD, scoreFromDimensions, verdictFromDimensions, verdictFromScore, } from "./domain/testQualityRubric.js";
+// ─── Ingestion sub-namespace (Issue #278) ──────────────────────────────────────
+// Pure-domain ingestion modelling: ADF parsing, untrusted-content normalisation,
+// source-mix planning, source reconciliation. No IO; consumes contract types only.
+export * as QualityIntelligenceIngestion from "./ingestion/index.js";
+// ─── Review sub-namespace (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; consumes contract types only.
+export * as QualityIntelligenceReview from "./review/index.js";
+// ─── Hardening sub-namespace (Issue #284) ──────────────────────────────────────
+// Pure adversarial-input predicates: path-safety, oversize guards, prompt-injection
+// scrubber. No IO; layered defence beside `QualityIntelligenceIngestion`.
+export * as QualityIntelligenceHardening from "./hardening/index.js";
+// ─── Export sub-namespace (Issue #283) ─────────────────────────────────────────
+// Pure-domain export adapters (CSV / JSON / TMS mappings) + bundle serialiser. No IO; the
+// server tier owns persistence + connector authorisation. TMS-targeted bundles must attest
+// redaction (enforced by the contract invariant).
+export * as QualityIntelligenceExport from "./export/index.js";
+// ─── Generation sub-namespace (Issue #272/#278/#279) ───────────────────────────
+// Pure model-routed generation prep + recovery: trusted prompt assembly, requirements-text
+// ingestion into content-bearing atoms, and deterministic model-output → candidate parsing.
+// No IO, no model call; the server tier supplies the Keiko Model Gateway port.
+export * as QualityIntelligenceGeneration from "./generation/index.js";
+// ─── Figma Screen-IR sub-namespace (Epic #750, Issue #752) ─────────────────────
+// Pure-domain Figma cleaner: raw scoped node tree → lean per-screen IR + deduped design tokens +
+// raw inter-screen links + reduction report. No IO, no network, no model. Downstream stages
+// (#753 evidence, #754 QI source, #811 nav graph, #812 a11y, #755 codegen) import from here.
+export * as QualityIntelligenceFigma from "./domain/figma/index.js";

package/dist/ingestion/adfParser.d.ts

@@ -0,0 +1,61 @@
+export type AdfParserErrorCode = "ROOT_NOT_OBJECT" | "ROOT_TYPE_MISMATCH" | "UNKNOWN_NODE_TYPE" | "NODE_NOT_OBJECT" | "MAX_DEPTH_EXCEEDED" | "MAX_NODES_EXCEEDED" | "CIRCULAR_REFERENCE" | "INVALID_HEADING_LEVEL";
+export declare class AdfParserError extends Error {
+    readonly code: AdfParserErrorCode;
+    readonly path: string;
+    constructor(code: AdfParserErrorCode, path: string, message: string);
+}
+export interface AdfParserOptions {
+    readonly maxNodes?: number;
+    readonly maxDepth?: number;
+    readonly maxTextBytes?: number;
+}
+export interface IngestedTextRun {
+    readonly text: string;
+    readonly clamped: boolean;
+    readonly markdownInjectionEscapes: number;
+}
+export type IngestedBlock = {
+    readonly kind: "paragraph";
+    readonly runs: readonly IngestedTextRun[];
+} | {
+    readonly kind: "heading";
+    readonly level: 1 | 2 | 3 | 4 | 5 | 6;
+    readonly runs: readonly IngestedTextRun[];
+} | {
+    readonly kind: "bulletList";
+    readonly items: readonly IngestedBlock[];
+} | {
+    readonly kind: "orderedList";
+    readonly items: readonly IngestedBlock[];
+} | {
+    readonly kind: "listItem";
+    readonly content: readonly IngestedBlock[];
+} | {
+    readonly kind: "codeBlock";
+    readonly language: string | null;
+    readonly text: string;
+} | {
+    readonly kind: "linkRef";
+    readonly displayText: string;
+    readonly hrefLabel: string;
+};
+export interface IngestedDocument {
+    readonly version: 1;
+    readonly blocks: readonly IngestedBlock[];
+    readonly stats: {
+        readonly nodes: number;
+        readonly maxDepthReached: number;
+        readonly truncatedBlocks: number;
+    };
+}
+/**
+ * Parse a JSON-decoded ADF tree into an `IngestedDocument`. Throws `AdfParserError` for
+ * unknown node types, malformed structure, depth-bombs, or circular references. Pure.
+ */
+export declare const parseAdfDocument: (raw: unknown, options?: AdfParserOptions) => IngestedDocument;
+export declare const ADF_PARSER_DEFAULTS: {
+    readonly maxNodes: 5000;
+    readonly maxDepth: 32;
+    readonly maxTextBytes: number;
+};
+//# sourceMappingURL=adfParser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adfParser.d.ts","sourceRoot":"","sources":["../../src/ingestion/adfParser.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,kBAAkB,GAC1B,iBAAiB,GACjB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,oBAAoB,GACpB,oBAAoB,GACpB,uBAAuB,CAAC;AAE5B,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,kBAAkB,CAAC;IACzC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBACjB,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMpE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;CAC3C;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,GACzE;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,CAAC;CAC3C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;KAClC,CAAC;CACH;AAuRD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,OAAO,EACZ,UAAS,gBAAqB,KAC7B,gBA8BF,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC"}

package/dist/ingestion/adfParser.js

@@ -0,0 +1,262 @@
+// Quality Intelligence — ADF parser (Epic #270, Issue #278).
+//
+// Deterministic parser for the Atlassian Document Format (ADF) JSON tree. Used to turn
+// structured Jira/Confluence-style content into a normalised internal `IngestedDocument`
+// shape the QI ingestion pipeline can map onto evidence atoms.
+//
+// Pure: no IO, no network, no `node:fs`, no `XMLHttpRequest`, no clock reads. Throws a
+// typed `AdfParserError` for malformed or unknown nodes. Bounded recursion + node count
+// keep depth-bomb inputs from blowing the stack or running for unbounded time.
+//
+// Structurally inspired by Test Intelligence reference (TI) ADF handling, but the
+// supported node set is a strict whitelist anchored on the Keiko contracts surface and
+// the audit-ledger normalisation rules already encoded in
+// @oscharko-dev/keiko-contracts/qualityIntelligence/ids.ts.
+import { normaliseUntrustedContent } from "./untrustedContentNormalisation.js";
+const DEFAULT_MAX_NODES = 5_000;
+const DEFAULT_MAX_DEPTH = 32;
+const DEFAULT_MAX_TEXT_BYTES = 64 * 1024;
+export class AdfParserError extends Error {
+    code;
+    path;
+    constructor(code, path, message) {
+        super(`[${code}] ${path}: ${message}`);
+        this.name = "AdfParserError";
+        this.code = code;
+        this.path = path;
+    }
+}
+const KNOWN_NODE_TYPES = new Set([
+    "doc",
+    "paragraph",
+    "heading",
+    "text",
+    "bulletList",
+    "orderedList",
+    "listItem",
+    "codeBlock",
+]);
+const isPlainObject = (value) => {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+const incrementNodes = (state, path) => {
+    state.nodeCount += 1;
+    if (state.nodeCount > state.maxNodes) {
+        throw new AdfParserError("MAX_NODES_EXCEEDED", path, `Exceeded maxNodes (${String(state.maxNodes)})`);
+    }
+};
+const checkDepth = (state, depth, path) => {
+    if (depth > state.maxDepth) {
+        throw new AdfParserError("MAX_DEPTH_EXCEEDED", path, `Exceeded maxDepth (${String(state.maxDepth)})`);
+    }
+    if (depth > state.maxDepthReached)
+        state.maxDepthReached = depth;
+};
+const markSeen = (state, node, path) => {
+    if (state.seen.has(node)) {
+        throw new AdfParserError("CIRCULAR_REFERENCE", path, "Node visited twice");
+    }
+    state.seen.add(node);
+};
+const assertObjectNode = (raw, path) => {
+    if (!isPlainObject(raw)) {
+        throw new AdfParserError("NODE_NOT_OBJECT", path, "Expected an object node");
+    }
+    return raw;
+};
+const getNodeType = (node, path) => {
+    const type = node.type;
+    if (typeof type !== "string") {
+        throw new AdfParserError("NODE_NOT_OBJECT", path, "Node `type` must be a string");
+    }
+    if (!KNOWN_NODE_TYPES.has(type)) {
+        throw new AdfParserError("UNKNOWN_NODE_TYPE", path, `Unknown node type "${type}"`);
+    }
+    return type;
+};
+const collectArrayContent = (node) => {
+    const content = node.content;
+    return Array.isArray(content) ? content : [];
+};
+const collectMarks = (node) => {
+    const marks = node.marks;
+    return Array.isArray(marks) ? marks : [];
+};
+const buildLinkRef = (rawText, marks, state) => {
+    for (const mark of marks) {
+        if (!isPlainObject(mark))
+            continue;
+        if (mark.type !== "link")
+            continue;
+        const attrs = mark.attrs;
+        const href = isPlainObject(attrs) && typeof attrs.href === "string" ? attrs.href : "(href)";
+        const hrefLabel = normaliseUntrustedContent(href, { maxBytes: state.maxTextBytes }).value;
+        const displayText = normaliseUntrustedContent(rawText, { maxBytes: state.maxTextBytes }).value;
+        return { kind: "linkRef", displayText, hrefLabel };
+    }
+    return null;
+};
+const parseTextNode = (node, path, state) => {
+    incrementNodes(state, path);
+    const rawText = typeof node.text === "string" ? node.text : "";
+    const marks = collectMarks(node);
+    const link = buildLinkRef(rawText, marks, state);
+    if (link !== null) {
+        return { run: null, link };
+    }
+    const normalised = normaliseUntrustedContent(rawText, { maxBytes: state.maxTextBytes });
+    return {
+        run: {
+            text: normalised.value,
+            clamped: normalised.clamped,
+            markdownInjectionEscapes: normalised.markdownInjectionEscapes,
+        },
+        link: null,
+    };
+};
+const parseInlineContent = (rawChildren, pathPrefix, depth, state) => {
+    checkDepth(state, depth, pathPrefix);
+    const runs = [];
+    const links = [];
+    rawChildren.forEach((child, index) => {
+        const path = `${pathPrefix}[${String(index)}]`;
+        const childNode = assertObjectNode(child, path);
+        markSeen(state, childNode, path);
+        const type = getNodeType(childNode, path);
+        if (type !== "text") {
+            throw new AdfParserError("UNKNOWN_NODE_TYPE", path, `Expected inline text, got "${type}"`);
+        }
+        const parsed = parseTextNode(childNode, path, state);
+        if (parsed.run !== null)
+            runs.push(parsed.run);
+        if (parsed.link !== null)
+            links.push(parsed.link);
+    });
+    return { runs, links };
+};
+const parseHeading = (node, path, depth, state) => {
+    const attrs = node.attrs;
+    const rawLevel = isPlainObject(attrs) ? attrs.level : undefined;
+    if (typeof rawLevel !== "number" || !Number.isInteger(rawLevel) || rawLevel < 1 || rawLevel > 6) {
+        throw new AdfParserError("INVALID_HEADING_LEVEL", path, "Heading level must be integer 1–6");
+    }
+    const inline = parseInlineContent(collectArrayContent(node), `${path}.content`, depth + 1, state);
+    return {
+        kind: "heading",
+        level: rawLevel,
+        runs: inline.runs,
+    };
+};
+const parseCodeBlock = (node, path, state) => {
+    const attrs = node.attrs;
+    const rawLanguage = isPlainObject(attrs) ? attrs.language : undefined;
+    const language = typeof rawLanguage === "string" && rawLanguage.length > 0
+        ? normaliseUntrustedContent(rawLanguage, { maxBytes: 256 }).value
+        : null;
+    const inline = collectArrayContent(node);
+    let combined = "";
+    inline.forEach((child, index) => {
+        const childPath = `${path}.content[${String(index)}]`;
+        const childNode = assertObjectNode(child, childPath);
+        markSeen(state, childNode, childPath);
+        incrementNodes(state, childPath);
+        if (childNode.type !== "text") {
+            throw new AdfParserError("UNKNOWN_NODE_TYPE", childPath, "codeBlock content must be text nodes");
+        }
+        const t = childNode.text;
+        if (typeof t === "string")
+            combined += t;
+    });
+    const normalised = normaliseUntrustedContent(combined, { maxBytes: state.maxTextBytes });
+    return { kind: "codeBlock", language, text: normalised.value };
+};
+const parseListItem = (node, path, depth, state) => {
+    const childPath = `${path}.content`;
+    const children = collectArrayContent(node);
+    const inner = [];
+    children.forEach((child, index) => {
+        const cp = `${childPath}[${String(index)}]`;
+        inner.push(parseBlock(child, cp, depth + 1, state));
+    });
+    return { kind: "listItem", content: inner };
+};
+const parseBulletOrOrderedList = (node, path, depth, state, kind) => {
+    const children = collectArrayContent(node);
+    const items = [];
+    children.forEach((child, index) => {
+        const cp = `${path}.content[${String(index)}]`;
+        const childNode = assertObjectNode(child, cp);
+        markSeen(state, childNode, cp);
+        incrementNodes(state, cp);
+        if (childNode.type !== "listItem") {
+            throw new AdfParserError("UNKNOWN_NODE_TYPE", cp, `${kind} children must be listItem nodes`);
+        }
+        items.push(parseListItem(childNode, cp, depth + 1, state));
+    });
+    return { kind, items };
+};
+const parseParagraph = (node, path, depth, state) => {
+    const inline = parseInlineContent(collectArrayContent(node), `${path}.content`, depth + 1, state);
+    return { kind: "paragraph", runs: inline.runs };
+};
+function parseBlock(raw, path, depth, state) {
+    const node = assertObjectNode(raw, path);
+    markSeen(state, node, path);
+    incrementNodes(state, path);
+    checkDepth(state, depth, path);
+    const type = getNodeType(node, path);
+    switch (type) {
+        case "paragraph":
+            return parseParagraph(node, path, depth, state);
+        case "heading":
+            return parseHeading(node, path, depth, state);
+        case "bulletList":
+            return parseBulletOrOrderedList(node, path, depth, state, "bulletList");
+        case "orderedList":
+            return parseBulletOrOrderedList(node, path, depth, state, "orderedList");
+        case "codeBlock":
+            return parseCodeBlock(node, path, state);
+        case "listItem":
+            return parseListItem(node, path, depth, state);
+        default:
+            throw new AdfParserError("UNKNOWN_NODE_TYPE", path, `Node type "${type}" is not a block-level node`);
+    }
+}
+/**
+ * Parse a JSON-decoded ADF tree into an `IngestedDocument`. Throws `AdfParserError` for
+ * unknown node types, malformed structure, depth-bombs, or circular references. Pure.
+ */
+export const parseAdfDocument = (raw, options = {}) => {
+    if (!isPlainObject(raw)) {
+        throw new AdfParserError("ROOT_NOT_OBJECT", "$", "ADF root must be a JSON object");
+    }
+    if (raw.type !== "doc") {
+        throw new AdfParserError("ROOT_TYPE_MISMATCH", "$", 'ADF root type must be "doc"');
+    }
+    const state = {
+        nodeCount: 0,
+        maxDepthReached: 0,
+        maxNodes: options.maxNodes ?? DEFAULT_MAX_NODES,
+        maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxTextBytes: options.maxTextBytes ?? DEFAULT_MAX_TEXT_BYTES,
+        seen: new WeakSet(),
+    };
+    markSeen(state, raw, "$");
+    incrementNodes(state, "$");
+    const children = collectArrayContent(raw);
+    const blocks = children.map((child, index) => parseBlock(child, `$.content[${String(index)}]`, 1, state));
+    return {
+        version: 1,
+        blocks,
+        stats: {
+            nodes: state.nodeCount,
+            maxDepthReached: state.maxDepthReached,
+            truncatedBlocks: 0,
+        },
+    };
+};
+export const ADF_PARSER_DEFAULTS = {
+    maxNodes: DEFAULT_MAX_NODES,
+    maxDepth: DEFAULT_MAX_DEPTH,
+    maxTextBytes: DEFAULT_MAX_TEXT_BYTES,
+};

package/dist/ingestion/index.d.ts

@@ -0,0 +1,6 @@
+export { normaliseUntrustedContent, UNTRUSTED_CONTENT_DEFAULT_MAX_BYTES, type NormaliseUntrustedContentOptions, type NormaliseUntrustedContentResult, } from "./untrustedContentNormalisation.js";
+export { parseAdfDocument, AdfParserError, ADF_PARSER_DEFAULTS, type AdfParserErrorCode, type AdfParserOptions, type IngestedBlock, type IngestedDocument, type IngestedTextRun, } from "./adfParser.js";
+export { planSourceMix, SOURCE_KIND_PRIORITY, type SourceMixPlan, type SourceMixPlanEntry, type SourceMixPlanOptions, } from "./sourceMixPlanning.js";
+export { reconcileSourceGroups, type ProvenanceEntry, type ReconciledSourceSet, type SourceGroup, } from "./sourceReconciliation.js";
+export { buildWorkspaceSourceEnvelopes, workspaceSourceMixPolicy, WorkspaceAdapterError, type BuildWorkspaceEnvelopesInput, type WorkspaceAdapterErrorCode, } from "./workspaceAdapter.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ingestion/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,yBAAyB,EACzB,mCAAmC,EACnC,KAAK,gCAAgC,EACrC,KAAK,+BAA+B,GACrC,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,GAC/B,MAAM,uBAAuB,CAAC"}

package/dist/ingestion/index.js

@@ -0,0 +1,10 @@
+// Public barrel for the Quality Intelligence ingestion sub-namespace (Epic #270, Issue #278).
+//
+// Pure-domain helpers that prepare structured + free-text inputs for the QI pipeline.
+// No IO. No network. No `node:fs`. All functions operate on contract types from
+// @oscharko-dev/keiko-contracts.
+export { normaliseUntrustedContent, UNTRUSTED_CONTENT_DEFAULT_MAX_BYTES, } from "./untrustedContentNormalisation.js";
+export { parseAdfDocument, AdfParserError, ADF_PARSER_DEFAULTS, } from "./adfParser.js";
+export { planSourceMix, SOURCE_KIND_PRIORITY, } from "./sourceMixPlanning.js";
+export { reconcileSourceGroups, } from "./sourceReconciliation.js";
+export { buildWorkspaceSourceEnvelopes, workspaceSourceMixPolicy, WorkspaceAdapterError, } from "./workspaceAdapter.js";

package/dist/ingestion/sourceMixPlanning.d.ts

@@ -0,0 +1,36 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+type Envelope = QualityIntelligence.QualityIntelligenceSourceEnvelope;
+type EnvelopeId = QualityIntelligence.QualityIntelligenceSourceEnvelopeId;
+type SourceKind = QualityIntelligence.QualityIntelligenceSourceKind;
+/** Per-kind priority weight: lower number = higher priority (planned earlier). */
+export declare const SOURCE_KIND_PRIORITY: Readonly<Record<SourceKind, number>>;
+export interface SourceMixPlanOptions {
+    /**
+     * Envelope display-label byte budget. An envelope whose label exceeds this is flagged
+     * as oversize but NOT dropped — the consumer decides what to do. Defaults to 256.
+     */
+    readonly maxLabelBytes?: number;
+    /**
+     * Hard cap on the number of envelopes the planner will keep. Defaults to 256. Extras
+     * appear in `droppedForCap` in original priority order.
+     */
+    readonly maxEnvelopes?: number;
+}
+export interface SourceMixPlanEntry {
+    readonly envelopeId: EnvelopeId;
+    readonly kind: SourceKind;
+    readonly priority: number;
+    readonly oversize: boolean;
+}
+export interface SourceMixPlan {
+    readonly entries: readonly SourceMixPlanEntry[];
+    readonly droppedForDuplicate: readonly EnvelopeId[];
+    readonly droppedForCap: readonly EnvelopeId[];
+    readonly oversizeCount: number;
+}
+/**
+ * Build a deterministic plan from a list of envelopes. Stable, pure.
+ */
+export declare const planSourceMix: (envelopes: readonly Envelope[], options?: SourceMixPlanOptions) => SourceMixPlan;
+export {};
+//# sourceMappingURL=sourceMixPlanning.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sourceMixPlanning.d.ts","sourceRoot":"","sources":["../../src/ingestion/sourceMixPlanning.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;AAC1E,KAAK,UAAU,GAAG,mBAAmB,CAAC,6BAA6B,CAAC;AAEpE,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAMrE,CAAC;AAIF,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,mBAAmB,EAAE,SAAS,UAAU,EAAE,CAAC;IACpD,QAAQ,CAAC,aAAa,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAaD;;GAEG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,SAAS,QAAQ,EAAE,EAC9B,UAAS,oBAAyB,KACjC,aAoCF,CAAC"}