open-multi-agent-kit 0.80.5 → 0.80.7

package/dist/core/orchestration/verification-contract.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Pure VerificationContract evaluation helpers.
+ *
+ * These functions evaluate a verification contract against already-captured
+ * evidence (command receipts, passed gate ids, agent contexts). They perform NO
+ * real command execution, NO filesystem access, and NO network calls — every
+ * input is passed in by the caller. This keeps them deterministic, fast, and
+ * safe to run inside any lane without write/execute scope.
+ *
+ * The shapes here are a focused, machine-verifiable subset of the orchestration
+ * verification contract (see `.omk/runs/omk-orchestration-upgrade-plan/
+ * verification-contract.md`). Downstream lanes add the executor (spawning,
+ * hashing, globbing) on top of these pure evaluators.
+ */
+/** Where an {@link OutputMatcher} should look for its pattern. */
+export type OutputSource = "stdout" | "stderr" | "combined";
+/** Match predicates supported by {@link evaluateOutputMatchers}. */
+export type OutputPredicate = "includes" | "regex" | "not-includes";
+/**
+ * A serializable matcher over a captured command stream.
+ *
+ * - `includes`     : the stream must contain `value` as a substring.
+ * - `regex`        : the stream must match the RegExp built from `value`.
+ * - `not-includes` : the stream must NOT contain `value` as a substring.
+ */
+export interface OutputMatcher {
+    readonly source: OutputSource;
+    readonly predicate: OutputPredicate;
+    readonly value: string;
+}
+/** Optional exit-code constraint for a {@link CommandGate}. */
+export type ExpectedExitCode = number | {
+    readonly min: number;
+    readonly max: number;
+};
+/**
+ * A single executable gate inside a verification contract. The gate itself is
+ * data only; {@link evaluateCommandGate} evaluates it against a receipt.
+ */
+export interface CommandGate {
+    readonly id: string;
+    readonly cmd: string;
+    readonly args?: readonly string[];
+    /** Exact code or inclusive range. Omit to skip the exit-code constraint. */
+    readonly expectedExitCode?: ExpectedExitCode;
+    readonly matchers?: readonly OutputMatcher[];
+    readonly timeoutMs: number;
+}
+/**
+ * Captured output of an already-executed command. `combined` defaults to
+ * `stdout + stderr` when omitted so matchers that select `combined` still work.
+ */
+export interface CommandReceipt {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly combined?: string;
+}
+/**
+ * An artifact existence/hash/size requirement. (Type shape only — artifact
+ * verification touches the filesystem and is implemented by the executor lane.)
+ */
+export interface ArtifactRule {
+    readonly id: string;
+    readonly pathGlob: string;
+    readonly mustExist: boolean;
+    readonly expectedHash?: string;
+    readonly sizeBytes?: {
+        readonly min?: number;
+        readonly max?: number;
+    };
+    readonly containment?: "file" | "directory" | "any";
+}
+/** Supported test frameworks for a {@link TestSelector}. */
+export type TestFramework = "vitest" | "jest" | "pytest" | "go";
+/**
+ * A test-suite selector. (Type shape only — running and parsing test output is
+ * implemented by the executor lane.)
+ */
+export interface TestSelector {
+    readonly id: string;
+    readonly framework: TestFramework;
+    readonly fileOrPattern: string;
+    readonly expectedResult?: {
+        readonly passed?: number;
+        readonly failed?: number;
+        readonly skipped?: number;
+    };
+    readonly timeoutMs: number;
+}
+/**
+ * How gate results are aggregated into a single pass/fail.
+ *
+ * - `all`    : every gate must pass (and there must be at least one gate).
+ * - `quorum` : at least `requiredPasses` gates must pass.
+ */
+export type EvidencePolicy = {
+    readonly mode: "all";
+} | {
+    readonly mode: "quorum";
+    readonly requiredPasses: number;
+};
+/** The kind of gate a {@link VerificationGateResult} summarizes. */
+export type GateKind = "command" | "artifact" | "test";
+/** Result of evaluating a single gate. */
+export interface VerificationGateResult {
+    readonly id: string;
+    readonly kind: GateKind;
+    readonly pass: boolean;
+    readonly exitCode?: number;
+    readonly matcherFailures?: readonly string[];
+    readonly errors?: readonly string[];
+}
+/** Top-level verification outcome after aggregation and policy checks. */
+export interface VerificationResult {
+    readonly pass: boolean;
+    readonly evidencePolicy: EvidencePolicy;
+    readonly gates: readonly VerificationGateResult[];
+    readonly traceabilityOk: boolean;
+    readonly independenceOk: boolean;
+    readonly errorSummary?: string;
+}
+/**
+ * Maps a requirement to the gate ids that prove it. `minPassingGates` defaults
+ * to 1 when omitted.
+ */
+export interface RequirementLink {
+    readonly requirementId: string;
+    readonly gateIds: readonly string[];
+    readonly minPassingGates?: number;
+}
+/** Identity of an executor or reviewer agent for independence checks. */
+export interface AgentContext {
+    readonly modelId: string;
+    readonly contextId: string;
+    /** Reviewer-only: declares the reviewer ran in a freshly created context. */
+    readonly freshContext?: boolean;
+}
+/** Streams available to matchers. */
+export interface CommandOutputs {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly combined?: string;
+}
+/** Outcome of {@link evaluateOutputMatchers}. */
+export interface MatcherEvaluation {
+    readonly pass: boolean;
+    readonly failures: readonly string[];
+}
+/** Outcome of {@link aggregateGateResults}. */
+export interface AggregationEvaluation {
+    readonly pass: boolean;
+    readonly passedCount: number;
+}
+/** Outcome of {@link verifyTraceability}. */
+export interface TraceabilityEvaluation {
+    readonly pass: boolean;
+    readonly failures: readonly string[];
+}
+/**
+ * Evaluate a list of {@link OutputMatcher}s against captured command streams.
+ * All matchers must pass. Invalid regex is treated as a failure (never thrown).
+ */
+export declare function evaluateOutputMatchers(outputs: CommandOutputs, matchers: readonly OutputMatcher[]): MatcherEvaluation;
+/**
+ * Evaluate a {@link CommandGate} against an executed-command receipt. The gate
+ * passes when the exit code satisfies `expectedExitCode` (if set) AND every
+ * matcher passes. No execution happens here.
+ */
+export declare function evaluateCommandGate(gate: CommandGate, receipt: CommandReceipt): VerificationGateResult;
+/**
+ * Aggregate gate results under an {@link EvidencePolicy}.
+ *
+ * - `all`    : passes only when there is at least one gate and every gate passes.
+ * - `quorum` : passes when at least `requiredPasses` gates pass.
+ */
+export declare function aggregateGateResults(results: readonly VerificationGateResult[], policy: EvidencePolicy): AggregationEvaluation;
+/**
+ * Verify every requirement id is covered by enough passed gates.
+ *
+ * For each requirement id in `requirements`, its {@link RequirementLink} must
+ * exist and at least `minPassingGates` (default 1) of its linked gate ids must
+ * appear in `passedGateIds`. A missing link is a traceability gap.
+ */
+export declare function verifyTraceability(requirements: readonly string[], links: readonly RequirementLink[], passedGateIds: readonly string[]): TraceabilityEvaluation;
+/**
+ * Check reviewer/executor independence.
+ *
+ * Passes only when:
+ *   - the reviewer's model differs from the executor's model, OR
+ *   - the reviewer's context differs AND the reviewer declared `freshContext`.
+ *
+ * This is the fail-closed gate that prevents a node's executor from also being
+ * its verifier.
+ */
+export declare function checkReviewerExecutorIndependence(executor: AgentContext, reviewer: AgentContext): boolean;
+//# sourceMappingURL=verification-contract.d.ts.map

package/dist/core/orchestration/verification-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-contract.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/verification-contract.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure VerificationContract evaluation helpers.\n *\n * These functions evaluate a verification contract against already-captured\n * evidence (command receipts, passed gate ids, agent contexts). They perform NO\n * real command execution, NO filesystem access, and NO network calls — every\n * input is passed in by the caller. This keeps them deterministic, fast, and\n * safe to run inside any lane without write/execute scope.\n *\n * The shapes here are a focused, machine-verifiable subset of the orchestration\n * verification contract (see `.omk/runs/omk-orchestration-upgrade-plan/\n * verification-contract.md`). Downstream lanes add the executor (spawning,\n * hashing, globbing) on top of these pure evaluators.\n */\n\n/** Where an {@link OutputMatcher} should look for its pattern. */\nexport type OutputSource = \"stdout\" | \"stderr\" | \"combined\";\n\n/** Match predicates supported by {@link evaluateOutputMatchers}. */\nexport type OutputPredicate = \"includes\" | \"regex\" | \"not-includes\";\n\n/**\n * A serializable matcher over a captured command stream.\n *\n * - `includes`     : the stream must contain `value` as a substring.\n * - `regex`        : the stream must match the RegExp built from `value`.\n * - `not-includes` : the stream must NOT contain `value` as a substring.\n */\nexport interface OutputMatcher {\n\treadonly source: OutputSource;\n\treadonly predicate: OutputPredicate;\n\treadonly value: string;\n}\n\n/** Optional exit-code constraint for a {@link CommandGate}. */\nexport type ExpectedExitCode = number | { readonly min: number; readonly max: number };\n\n/**\n * A single executable gate inside a verification contract. The gate itself is\n * data only; {@link evaluateCommandGate} evaluates it against a receipt.\n */\nexport interface CommandGate {\n\treadonly id: string;\n\treadonly cmd: string;\n\treadonly args?: readonly string[];\n\t/** Exact code or inclusive range. Omit to skip the exit-code constraint. */\n\treadonly expectedExitCode?: ExpectedExitCode;\n\treadonly matchers?: readonly OutputMatcher[];\n\treadonly timeoutMs: number;\n}\n\n/**\n * Captured output of an already-executed command. `combined` defaults to\n * `stdout + stderr` when omitted so matchers that select `combined` still work.\n */\nexport interface CommandReceipt {\n\treadonly exitCode: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n\treadonly combined?: string;\n}\n\n/**\n * An artifact existence/hash/size requirement. (Type shape only — artifact\n * verification touches the filesystem and is implemented by the executor lane.)\n */\nexport interface ArtifactRule {\n\treadonly id: string;\n\treadonly pathGlob: string;\n\treadonly mustExist: boolean;\n\treadonly expectedHash?: string;\n\treadonly sizeBytes?: { readonly min?: number; readonly max?: number };\n\treadonly containment?: \"file\" | \"directory\" | \"any\";\n}\n\n/** Supported test frameworks for a {@link TestSelector}. */\nexport type TestFramework = \"vitest\" | \"jest\" | \"pytest\" | \"go\";\n\n/**\n * A test-suite selector. (Type shape only — running and parsing test output is\n * implemented by the executor lane.)\n */\nexport interface TestSelector {\n\treadonly id: string;\n\treadonly framework: TestFramework;\n\treadonly fileOrPattern: string;\n\treadonly expectedResult?: {\n\t\treadonly passed?: number;\n\t\treadonly failed?: number;\n\t\treadonly skipped?: number;\n\t};\n\treadonly timeoutMs: number;\n}\n\n/**\n * How gate results are aggregated into a single pass/fail.\n *\n * - `all`    : every gate must pass (and there must be at least one gate).\n * - `quorum` : at least `requiredPasses` gates must pass.\n */\nexport type EvidencePolicy = { readonly mode: \"all\" } | { readonly mode: \"quorum\"; readonly requiredPasses: number };\n\n/** The kind of gate a {@link VerificationGateResult} summarizes. */\nexport type GateKind = \"command\" | \"artifact\" | \"test\";\n\n/** Result of evaluating a single gate. */\nexport interface VerificationGateResult {\n\treadonly id: string;\n\treadonly kind: GateKind;\n\treadonly pass: boolean;\n\treadonly exitCode?: number;\n\treadonly matcherFailures?: readonly string[];\n\treadonly errors?: readonly string[];\n}\n\n/** Top-level verification outcome after aggregation and policy checks. */\nexport interface VerificationResult {\n\treadonly pass: boolean;\n\treadonly evidencePolicy: EvidencePolicy;\n\treadonly gates: readonly VerificationGateResult[];\n\treadonly traceabilityOk: boolean;\n\treadonly independenceOk: boolean;\n\treadonly errorSummary?: string;\n}\n\n/**\n * Maps a requirement to the gate ids that prove it. `minPassingGates` defaults\n * to 1 when omitted.\n */\nexport interface RequirementLink {\n\treadonly requirementId: string;\n\treadonly gateIds: readonly string[];\n\treadonly minPassingGates?: number;\n}\n\n/** Identity of an executor or reviewer agent for independence checks. */\nexport interface AgentContext {\n\treadonly modelId: string;\n\treadonly contextId: string;\n\t/** Reviewer-only: declares the reviewer ran in a freshly created context. */\n\treadonly freshContext?: boolean;\n}\n\n/** Streams available to matchers. */\nexport interface CommandOutputs {\n\treadonly stdout: string;\n\treadonly stderr: string;\n\treadonly combined?: string;\n}\n\n/** Outcome of {@link evaluateOutputMatchers}. */\nexport interface MatcherEvaluation {\n\treadonly pass: boolean;\n\treadonly failures: readonly string[];\n}\n\n/** Outcome of {@link aggregateGateResults}. */\nexport interface AggregationEvaluation {\n\treadonly pass: boolean;\n\treadonly passedCount: number;\n}\n\n/** Outcome of {@link verifyTraceability}. */\nexport interface TraceabilityEvaluation {\n\treadonly pass: boolean;\n\treadonly failures: readonly string[];\n}\n\nfunction selectStream(outputs: CommandOutputs, source: OutputSource): string {\n\tif (source === \"stdout\") return outputs.stdout;\n\tif (source === \"stderr\") return outputs.stderr;\n\t// `combined` defaults to stdout + stderr so callers can omit it.\n\treturn outputs.combined ?? `${outputs.stdout}${outputs.stderr}`;\n}\n\nfunction describeMatcher(matcher: OutputMatcher): string {\n\treturn `${matcher.source}/${matcher.predicate}=${JSON.stringify(matcher.value)}`;\n}\n\n/**\n * Evaluate a list of {@link OutputMatcher}s against captured command streams.\n * All matchers must pass. Invalid regex is treated as a failure (never thrown).\n */\nexport function evaluateOutputMatchers(outputs: CommandOutputs, matchers: readonly OutputMatcher[]): MatcherEvaluation {\n\tconst failures: string[] = [];\n\tfor (const matcher of matchers) {\n\t\tconst stream = selectStream(outputs, matcher.source);\n\t\tlet ok: boolean;\n\t\tif (matcher.predicate === \"includes\") {\n\t\t\tok = stream.includes(matcher.value);\n\t\t} else if (matcher.predicate === \"not-includes\") {\n\t\t\tok = !stream.includes(matcher.value);\n\t\t} else {\n\t\t\t// regex: a malformed pattern is a failed matcher, not a crash.\n\t\t\ttry {\n\t\t\t\tok = new RegExp(matcher.value).test(stream);\n\t\t\t} catch {\n\t\t\t\tfailures.push(`invalid regex for ${describeMatcher(matcher)}`);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\tif (!ok) {\n\t\t\tfailures.push(`matcher failed: ${describeMatcher(matcher)}`);\n\t\t}\n\t}\n\treturn { pass: failures.length === 0, failures };\n}\n\nfunction evaluateExitCode(expected: ExpectedExitCode | undefined, exitCode: number): boolean {\n\tif (expected === undefined) return true;\n\tif (typeof expected === \"number\") return exitCode === expected;\n\treturn exitCode >= expected.min && exitCode <= expected.max;\n}\n\n/**\n * Evaluate a {@link CommandGate} against an executed-command receipt. The gate\n * passes when the exit code satisfies `expectedExitCode` (if set) AND every\n * matcher passes. No execution happens here.\n */\nexport function evaluateCommandGate(gate: CommandGate, receipt: CommandReceipt): VerificationGateResult {\n\tconst errors: string[] = [];\n\tconst exitOk = evaluateExitCode(gate.expectedExitCode, receipt.exitCode);\n\tif (!exitOk) {\n\t\terrors.push(`exit code ${receipt.exitCode} did not satisfy ${JSON.stringify(gate.expectedExitCode)}`);\n\t}\n\tconst matcherResult = evaluateOutputMatchers(receipt, gate.matchers ?? []);\n\tconst pass = exitOk && matcherResult.pass;\n\treturn {\n\t\tid: gate.id,\n\t\tkind: \"command\",\n\t\tpass,\n\t\texitCode: receipt.exitCode,\n\t\t...(matcherResult.failures.length > 0 ? { matcherFailures: matcherResult.failures } : {}),\n\t\t...(errors.length > 0 ? { errors } : {}),\n\t};\n}\n\n/**\n * Aggregate gate results under an {@link EvidencePolicy}.\n *\n * - `all`    : passes only when there is at least one gate and every gate passes.\n * - `quorum` : passes when at least `requiredPasses` gates pass.\n */\nexport function aggregateGateResults(\n\tresults: readonly VerificationGateResult[],\n\tpolicy: EvidencePolicy,\n): AggregationEvaluation {\n\tconst passedCount = results.filter((r) => r.pass).length;\n\tlet pass: boolean;\n\tif (policy.mode === \"all\") {\n\t\tpass = results.length > 0 && passedCount === results.length;\n\t} else {\n\t\tpass = passedCount >= policy.requiredPasses;\n\t}\n\treturn { pass, passedCount };\n}\n\n/**\n * Verify every requirement id is covered by enough passed gates.\n *\n * For each requirement id in `requirements`, its {@link RequirementLink} must\n * exist and at least `minPassingGates` (default 1) of its linked gate ids must\n * appear in `passedGateIds`. A missing link is a traceability gap.\n */\nexport function verifyTraceability(\n\trequirements: readonly string[],\n\tlinks: readonly RequirementLink[],\n\tpassedGateIds: readonly string[],\n): TraceabilityEvaluation {\n\tconst failures: string[] = [];\n\tconst passed = new Set(passedGateIds);\n\tconst byId = new Map<string, RequirementLink>();\n\tfor (const link of links) byId.set(link.requirementId, link);\n\tfor (const requirementId of requirements) {\n\t\tconst link = byId.get(requirementId);\n\t\tif (!link) {\n\t\t\tfailures.push(`requirement ${requirementId} has no gate link (traceability gap)`);\n\t\t\tcontinue;\n\t\t}\n\t\tconst minPassing = link.minPassingGates ?? 1;\n\t\tconst passing = link.gateIds.filter((id) => passed.has(id)).length;\n\t\tif (passing < minPassing) {\n\t\t\tfailures.push(`requirement ${requirementId} covered by ${passing}/${minPassing} passed gates`);\n\t\t}\n\t}\n\treturn { pass: failures.length === 0, failures };\n}\n\n/**\n * Check reviewer/executor independence.\n *\n * Passes only when:\n *   - the reviewer's model differs from the executor's model, OR\n *   - the reviewer's context differs AND the reviewer declared `freshContext`.\n *\n * This is the fail-closed gate that prevents a node's executor from also being\n * its verifier.\n */\nexport function checkReviewerExecutorIndependence(executor: AgentContext, reviewer: AgentContext): boolean {\n\tconst differentModel = reviewer.modelId !== executor.modelId;\n\tconst freshDifferentContext = reviewer.contextId !== executor.contextId && reviewer.freshContext === true;\n\treturn differentModel || freshDifferentContext;\n}\n"]}

package/dist/core/orchestration/verification-contract.js

@@ -0,0 +1,145 @@
+/**
+ * Pure VerificationContract evaluation helpers.
+ *
+ * These functions evaluate a verification contract against already-captured
+ * evidence (command receipts, passed gate ids, agent contexts). They perform NO
+ * real command execution, NO filesystem access, and NO network calls — every
+ * input is passed in by the caller. This keeps them deterministic, fast, and
+ * safe to run inside any lane without write/execute scope.
+ *
+ * The shapes here are a focused, machine-verifiable subset of the orchestration
+ * verification contract (see `.omk/runs/omk-orchestration-upgrade-plan/
+ * verification-contract.md`). Downstream lanes add the executor (spawning,
+ * hashing, globbing) on top of these pure evaluators.
+ */
+function selectStream(outputs, source) {
+    if (source === "stdout")
+        return outputs.stdout;
+    if (source === "stderr")
+        return outputs.stderr;
+    // `combined` defaults to stdout + stderr so callers can omit it.
+    return outputs.combined ?? `${outputs.stdout}${outputs.stderr}`;
+}
+function describeMatcher(matcher) {
+    return `${matcher.source}/${matcher.predicate}=${JSON.stringify(matcher.value)}`;
+}
+/**
+ * Evaluate a list of {@link OutputMatcher}s against captured command streams.
+ * All matchers must pass. Invalid regex is treated as a failure (never thrown).
+ */
+export function evaluateOutputMatchers(outputs, matchers) {
+    const failures = [];
+    for (const matcher of matchers) {
+        const stream = selectStream(outputs, matcher.source);
+        let ok;
+        if (matcher.predicate === "includes") {
+            ok = stream.includes(matcher.value);
+        }
+        else if (matcher.predicate === "not-includes") {
+            ok = !stream.includes(matcher.value);
+        }
+        else {
+            // regex: a malformed pattern is a failed matcher, not a crash.
+            try {
+                ok = new RegExp(matcher.value).test(stream);
+            }
+            catch {
+                failures.push(`invalid regex for ${describeMatcher(matcher)}`);
+                continue;
+            }
+        }
+        if (!ok) {
+            failures.push(`matcher failed: ${describeMatcher(matcher)}`);
+        }
+    }
+    return { pass: failures.length === 0, failures };
+}
+function evaluateExitCode(expected, exitCode) {
+    if (expected === undefined)
+        return true;
+    if (typeof expected === "number")
+        return exitCode === expected;
+    return exitCode >= expected.min && exitCode <= expected.max;
+}
+/**
+ * Evaluate a {@link CommandGate} against an executed-command receipt. The gate
+ * passes when the exit code satisfies `expectedExitCode` (if set) AND every
+ * matcher passes. No execution happens here.
+ */
+export function evaluateCommandGate(gate, receipt) {
+    const errors = [];
+    const exitOk = evaluateExitCode(gate.expectedExitCode, receipt.exitCode);
+    if (!exitOk) {
+        errors.push(`exit code ${receipt.exitCode} did not satisfy ${JSON.stringify(gate.expectedExitCode)}`);
+    }
+    const matcherResult = evaluateOutputMatchers(receipt, gate.matchers ?? []);
+    const pass = exitOk && matcherResult.pass;
+    return {
+        id: gate.id,
+        kind: "command",
+        pass,
+        exitCode: receipt.exitCode,
+        ...(matcherResult.failures.length > 0 ? { matcherFailures: matcherResult.failures } : {}),
+        ...(errors.length > 0 ? { errors } : {}),
+    };
+}
+/**
+ * Aggregate gate results under an {@link EvidencePolicy}.
+ *
+ * - `all`    : passes only when there is at least one gate and every gate passes.
+ * - `quorum` : passes when at least `requiredPasses` gates pass.
+ */
+export function aggregateGateResults(results, policy) {
+    const passedCount = results.filter((r) => r.pass).length;
+    let pass;
+    if (policy.mode === "all") {
+        pass = results.length > 0 && passedCount === results.length;
+    }
+    else {
+        pass = passedCount >= policy.requiredPasses;
+    }
+    return { pass, passedCount };
+}
+/**
+ * Verify every requirement id is covered by enough passed gates.
+ *
+ * For each requirement id in `requirements`, its {@link RequirementLink} must
+ * exist and at least `minPassingGates` (default 1) of its linked gate ids must
+ * appear in `passedGateIds`. A missing link is a traceability gap.
+ */
+export function verifyTraceability(requirements, links, passedGateIds) {
+    const failures = [];
+    const passed = new Set(passedGateIds);
+    const byId = new Map();
+    for (const link of links)
+        byId.set(link.requirementId, link);
+    for (const requirementId of requirements) {
+        const link = byId.get(requirementId);
+        if (!link) {
+            failures.push(`requirement ${requirementId} has no gate link (traceability gap)`);
+            continue;
+        }
+        const minPassing = link.minPassingGates ?? 1;
+        const passing = link.gateIds.filter((id) => passed.has(id)).length;
+        if (passing < minPassing) {
+            failures.push(`requirement ${requirementId} covered by ${passing}/${minPassing} passed gates`);
+        }
+    }
+    return { pass: failures.length === 0, failures };
+}
+/**
+ * Check reviewer/executor independence.
+ *
+ * Passes only when:
+ *   - the reviewer's model differs from the executor's model, OR
+ *   - the reviewer's context differs AND the reviewer declared `freshContext`.
+ *
+ * This is the fail-closed gate that prevents a node's executor from also being
+ * its verifier.
+ */
+export function checkReviewerExecutorIndependence(executor, reviewer) {
+    const differentModel = reviewer.modelId !== executor.modelId;
+    const freshDifferentContext = reviewer.contextId !== executor.contextId && reviewer.freshContext === true;
+    return differentModel || freshDifferentContext;
+}
+//# sourceMappingURL=verification-contract.js.map

package/dist/core/orchestration/verification-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-contract.js","sourceRoot":"","sources":["../../../src/core/orchestration/verification-contract.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure VerificationContract evaluation helpers.\n *\n * These functions evaluate a verification contract against already-captured\n * evidence (command receipts, passed gate ids, agent contexts). They perform NO\n * real command execution, NO filesystem access, and NO network calls — every\n * input is passed in by the caller. This keeps them deterministic, fast, and\n * safe to run inside any lane without write/execute scope.\n *\n * The shapes here are a focused, machine-verifiable subset of the orchestration\n * verification contract (see `.omk/runs/omk-orchestration-upgrade-plan/\n * verification-contract.md`). Downstream lanes add the executor (spawning,\n * hashing, globbing) on top of these pure evaluators.\n */\n\n/** Where an {@link OutputMatcher} should look for its pattern. */\nexport type OutputSource = \"stdout\" | \"stderr\" | \"combined\";\n\n/** Match predicates supported by {@link evaluateOutputMatchers}. */\nexport type OutputPredicate = \"includes\" | \"regex\" | \"not-includes\";\n\n/**\n * A serializable matcher over a captured command stream.\n *\n * - `includes`     : the stream must contain `value` as a substring.\n * - `regex`        : the stream must match the RegExp built from `value`.\n * - `not-includes` : the stream must NOT contain `value` as a substring.\n */\nexport interface OutputMatcher {\n\treadonly source: OutputSource;\n\treadonly predicate: OutputPredicate;\n\treadonly value: string;\n}\n\n/** Optional exit-code constraint for a {@link CommandGate}. */\nexport type ExpectedExitCode = number | { readonly min: number; readonly max: number };\n\n/**\n * A single executable gate inside a verification contract. The gate itself is\n * data only; {@link evaluateCommandGate} evaluates it against a receipt.\n */\nexport interface CommandGate {\n\treadonly id: string;\n\treadonly cmd: string;\n\treadonly args?: readonly string[];\n\t/** Exact code or inclusive range. Omit to skip the exit-code constraint. */\n\treadonly expectedExitCode?: ExpectedExitCode;\n\treadonly matchers?: readonly OutputMatcher[];\n\treadonly timeoutMs: number;\n}\n\n/**\n * Captured output of an already-executed command. `combined` defaults to\n * `stdout + stderr` when omitted so matchers that select `combined` still work.\n */\nexport interface CommandReceipt {\n\treadonly exitCode: number;\n\treadonly stdout: string;\n\treadonly stderr: string;\n\treadonly combined?: string;\n}\n\n/**\n * An artifact existence/hash/size requirement. (Type shape only — artifact\n * verification touches the filesystem and is implemented by the executor lane.)\n */\nexport interface ArtifactRule {\n\treadonly id: string;\n\treadonly pathGlob: string;\n\treadonly mustExist: boolean;\n\treadonly expectedHash?: string;\n\treadonly sizeBytes?: { readonly min?: number; readonly max?: number };\n\treadonly containment?: \"file\" | \"directory\" | \"any\";\n}\n\n/** Supported test frameworks for a {@link TestSelector}. */\nexport type TestFramework = \"vitest\" | \"jest\" | \"pytest\" | \"go\";\n\n/**\n * A test-suite selector. (Type shape only — running and parsing test output is\n * implemented by the executor lane.)\n */\nexport interface TestSelector {\n\treadonly id: string;\n\treadonly framework: TestFramework;\n\treadonly fileOrPattern: string;\n\treadonly expectedResult?: {\n\t\treadonly passed?: number;\n\t\treadonly failed?: number;\n\t\treadonly skipped?: number;\n\t};\n\treadonly timeoutMs: number;\n}\n\n/**\n * How gate results are aggregated into a single pass/fail.\n *\n * - `all`    : every gate must pass (and there must be at least one gate).\n * - `quorum` : at least `requiredPasses` gates must pass.\n */\nexport type EvidencePolicy = { readonly mode: \"all\" } | { readonly mode: \"quorum\"; readonly requiredPasses: number };\n\n/** The kind of gate a {@link VerificationGateResult} summarizes. */\nexport type GateKind = \"command\" | \"artifact\" | \"test\";\n\n/** Result of evaluating a single gate. */\nexport interface VerificationGateResult {\n\treadonly id: string;\n\treadonly kind: GateKind;\n\treadonly pass: boolean;\n\treadonly exitCode?: number;\n\treadonly matcherFailures?: readonly string[];\n\treadonly errors?: readonly string[];\n}\n\n/** Top-level verification outcome after aggregation and policy checks. */\nexport interface VerificationResult {\n\treadonly pass: boolean;\n\treadonly evidencePolicy: EvidencePolicy;\n\treadonly gates: readonly VerificationGateResult[];\n\treadonly traceabilityOk: boolean;\n\treadonly independenceOk: boolean;\n\treadonly errorSummary?: string;\n}\n\n/**\n * Maps a requirement to the gate ids that prove it. `minPassingGates` defaults\n * to 1 when omitted.\n */\nexport interface RequirementLink {\n\treadonly requirementId: string;\n\treadonly gateIds: readonly string[];\n\treadonly minPassingGates?: number;\n}\n\n/** Identity of an executor or reviewer agent for independence checks. */\nexport interface AgentContext {\n\treadonly modelId: string;\n\treadonly contextId: string;\n\t/** Reviewer-only: declares the reviewer ran in a freshly created context. */\n\treadonly freshContext?: boolean;\n}\n\n/** Streams available to matchers. */\nexport interface CommandOutputs {\n\treadonly stdout: string;\n\treadonly stderr: string;\n\treadonly combined?: string;\n}\n\n/** Outcome of {@link evaluateOutputMatchers}. */\nexport interface MatcherEvaluation {\n\treadonly pass: boolean;\n\treadonly failures: readonly string[];\n}\n\n/** Outcome of {@link aggregateGateResults}. */\nexport interface AggregationEvaluation {\n\treadonly pass: boolean;\n\treadonly passedCount: number;\n}\n\n/** Outcome of {@link verifyTraceability}. */\nexport interface TraceabilityEvaluation {\n\treadonly pass: boolean;\n\treadonly failures: readonly string[];\n}\n\nfunction selectStream(outputs: CommandOutputs, source: OutputSource): string {\n\tif (source === \"stdout\") return outputs.stdout;\n\tif (source === \"stderr\") return outputs.stderr;\n\t// `combined` defaults to stdout + stderr so callers can omit it.\n\treturn outputs.combined ?? `${outputs.stdout}${outputs.stderr}`;\n}\n\nfunction describeMatcher(matcher: OutputMatcher): string {\n\treturn `${matcher.source}/${matcher.predicate}=${JSON.stringify(matcher.value)}`;\n}\n\n/**\n * Evaluate a list of {@link OutputMatcher}s against captured command streams.\n * All matchers must pass. Invalid regex is treated as a failure (never thrown).\n */\nexport function evaluateOutputMatchers(outputs: CommandOutputs, matchers: readonly OutputMatcher[]): MatcherEvaluation {\n\tconst failures: string[] = [];\n\tfor (const matcher of matchers) {\n\t\tconst stream = selectStream(outputs, matcher.source);\n\t\tlet ok: boolean;\n\t\tif (matcher.predicate === \"includes\") {\n\t\t\tok = stream.includes(matcher.value);\n\t\t} else if (matcher.predicate === \"not-includes\") {\n\t\t\tok = !stream.includes(matcher.value);\n\t\t} else {\n\t\t\t// regex: a malformed pattern is a failed matcher, not a crash.\n\t\t\ttry {\n\t\t\t\tok = new RegExp(matcher.value).test(stream);\n\t\t\t} catch {\n\t\t\t\tfailures.push(`invalid regex for ${describeMatcher(matcher)}`);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\tif (!ok) {\n\t\t\tfailures.push(`matcher failed: ${describeMatcher(matcher)}`);\n\t\t}\n\t}\n\treturn { pass: failures.length === 0, failures };\n}\n\nfunction evaluateExitCode(expected: ExpectedExitCode | undefined, exitCode: number): boolean {\n\tif (expected === undefined) return true;\n\tif (typeof expected === \"number\") return exitCode === expected;\n\treturn exitCode >= expected.min && exitCode <= expected.max;\n}\n\n/**\n * Evaluate a {@link CommandGate} against an executed-command receipt. The gate\n * passes when the exit code satisfies `expectedExitCode` (if set) AND every\n * matcher passes. No execution happens here.\n */\nexport function evaluateCommandGate(gate: CommandGate, receipt: CommandReceipt): VerificationGateResult {\n\tconst errors: string[] = [];\n\tconst exitOk = evaluateExitCode(gate.expectedExitCode, receipt.exitCode);\n\tif (!exitOk) {\n\t\terrors.push(`exit code ${receipt.exitCode} did not satisfy ${JSON.stringify(gate.expectedExitCode)}`);\n\t}\n\tconst matcherResult = evaluateOutputMatchers(receipt, gate.matchers ?? []);\n\tconst pass = exitOk && matcherResult.pass;\n\treturn {\n\t\tid: gate.id,\n\t\tkind: \"command\",\n\t\tpass,\n\t\texitCode: receipt.exitCode,\n\t\t...(matcherResult.failures.length > 0 ? { matcherFailures: matcherResult.failures } : {}),\n\t\t...(errors.length > 0 ? { errors } : {}),\n\t};\n}\n\n/**\n * Aggregate gate results under an {@link EvidencePolicy}.\n *\n * - `all`    : passes only when there is at least one gate and every gate passes.\n * - `quorum` : passes when at least `requiredPasses` gates pass.\n */\nexport function aggregateGateResults(\n\tresults: readonly VerificationGateResult[],\n\tpolicy: EvidencePolicy,\n): AggregationEvaluation {\n\tconst passedCount = results.filter((r) => r.pass).length;\n\tlet pass: boolean;\n\tif (policy.mode === \"all\") {\n\t\tpass = results.length > 0 && passedCount === results.length;\n\t} else {\n\t\tpass = passedCount >= policy.requiredPasses;\n\t}\n\treturn { pass, passedCount };\n}\n\n/**\n * Verify every requirement id is covered by enough passed gates.\n *\n * For each requirement id in `requirements`, its {@link RequirementLink} must\n * exist and at least `minPassingGates` (default 1) of its linked gate ids must\n * appear in `passedGateIds`. A missing link is a traceability gap.\n */\nexport function verifyTraceability(\n\trequirements: readonly string[],\n\tlinks: readonly RequirementLink[],\n\tpassedGateIds: readonly string[],\n): TraceabilityEvaluation {\n\tconst failures: string[] = [];\n\tconst passed = new Set(passedGateIds);\n\tconst byId = new Map<string, RequirementLink>();\n\tfor (const link of links) byId.set(link.requirementId, link);\n\tfor (const requirementId of requirements) {\n\t\tconst link = byId.get(requirementId);\n\t\tif (!link) {\n\t\t\tfailures.push(`requirement ${requirementId} has no gate link (traceability gap)`);\n\t\t\tcontinue;\n\t\t}\n\t\tconst minPassing = link.minPassingGates ?? 1;\n\t\tconst passing = link.gateIds.filter((id) => passed.has(id)).length;\n\t\tif (passing < minPassing) {\n\t\t\tfailures.push(`requirement ${requirementId} covered by ${passing}/${minPassing} passed gates`);\n\t\t}\n\t}\n\treturn { pass: failures.length === 0, failures };\n}\n\n/**\n * Check reviewer/executor independence.\n *\n * Passes only when:\n *   - the reviewer's model differs from the executor's model, OR\n *   - the reviewer's context differs AND the reviewer declared `freshContext`.\n *\n * This is the fail-closed gate that prevents a node's executor from also being\n * its verifier.\n */\nexport function checkReviewerExecutorIndependence(executor: AgentContext, reviewer: AgentContext): boolean {\n\tconst differentModel = reviewer.modelId !== executor.modelId;\n\tconst freshDifferentContext = reviewer.contextId !== executor.contextId && reviewer.freshContext === true;\n\treturn differentModel || freshDifferentContext;\n}\n"]}

package/dist/core/package-composition.d.ts

@@ -0,0 +1,68 @@
+import type { ProcurementReview } from "./package-procurement.ts";
+import type { PackageSource } from "./settings-manager.ts";
+export type CompositionSurface = "theme" | "footer" | "header" | "editor" | "tool-row" | "assistant-markdown" | "status" | "permission" | "structured-input" | "report-preview" | "loadout";
+export type OmkOwnedDomain = "ontology" | "search" | "memory" | "cache" | "compaction" | "multi-agent" | "session" | "scheduler";
+export type CompositionVerdict = "admit" | "reject" | "defer" | "canary";
+export interface CompositionResourceFilter {
+    extensions: boolean;
+    skills: boolean;
+    prompts: boolean;
+    themes: boolean;
+}
+export interface SurfaceOwnerRule {
+    surface: CompositionSurface;
+    ownerPackageIdentity: string;
+}
+export interface PackageCompositionPolicy {
+    readonly omkOwnedDomains: readonly OmkOwnedDomain[];
+    readonly surfaceOwnership: readonly SurfaceOwnerRule[];
+    readonly allowedResources: Readonly<Record<string, Partial<CompositionResourceFilter>>>;
+    readonly capabilityToSurfaces: Readonly<Record<string, readonly CompositionSurface[]>>;
+    readonly capabilityToOmkDomains: Readonly<Record<string, readonly OmkOwnedDomain[]>>;
+}
+export interface CompositionInput {
+    identity: string;
+    review: ProcurementReview;
+    requestedSurfaces?: readonly CompositionSurface[];
+}
+export interface CompositionConflict {
+    kind: "duplicate-surface-owner" | "omk-domain-mutation" | "unapproved-surface" | "capability-surface-mismatch" | "resource-filter-blocked";
+    surface?: CompositionSurface;
+    domain?: OmkOwnedDomain;
+    owner?: string;
+    capability?: string;
+    reason: string;
+}
+export interface CompositionReview {
+    identity: string;
+    verdict: CompositionVerdict;
+    allowedResources: CompositionResourceFilter;
+    admittedSurfaces: CompositionSurface[];
+    conflicts: CompositionConflict[];
+    deferredReason?: string;
+    rejectedReasons: string[];
+}
+export interface CompositionPromotionRecord {
+    schemaVersion: "omk.package-composition.promotion.v1";
+    identity: string;
+    source: string;
+    scope: "project";
+    allowedResources: CompositionResourceFilter;
+    admittedSurfaces: CompositionSurface[];
+    reviewedAt: string;
+    reviewedBy: "manual" | "root-orchestrator";
+}
+export declare function createDefaultCompositionPolicy(): PackageCompositionPolicy;
+export declare function checkSingleSurfaceOwner(identity: string, requestedSurfaces: readonly CompositionSurface[], existingOwners: readonly SurfaceOwnerRule[]): CompositionConflict[];
+export declare function checkOmkDomainMutation(identity: string, capabilities: readonly string[], policy: PackageCompositionPolicy): CompositionConflict[];
+export declare function checkCapabilitySurfaceMatch(identity: string, requestedSurfaces: readonly CompositionSurface[], capabilities: readonly string[], policy: PackageCompositionPolicy): CompositionConflict[];
+export declare function resolveResourceFilter(identity: string, policy: PackageCompositionPolicy): CompositionResourceFilter;
+export declare function inferRequestedSurfaces(review: ProcurementReview, policy: PackageCompositionPolicy): CompositionSurface[];
+export declare function composePackage(input: CompositionInput, policy: PackageCompositionPolicy): CompositionReview;
+export declare function composeCandidateBatch(inputs: readonly CompositionInput[], basePolicy: PackageCompositionPolicy): CompositionReview[];
+export declare function toPackageSource(review: CompositionReview): PackageSource;
+export declare function createPromotionRecord(review: CompositionReview, source: string, options?: {
+    reviewedBy?: "manual" | "root-orchestrator";
+    now?: Date;
+}): CompositionPromotionRecord;
+//# sourceMappingURL=package-composition.d.ts.map

package/dist/core/package-composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-composition.d.ts","sourceRoot":"","sources":["../../src/core/package-composition.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProcurementReview } from \"./package-procurement.ts\";\nimport type { PackageSource } from \"./settings-manager.ts\";\n\nexport type CompositionSurface =\n\t| \"theme\"\n\t| \"footer\"\n\t| \"header\"\n\t| \"editor\"\n\t| \"tool-row\"\n\t| \"assistant-markdown\"\n\t| \"status\"\n\t| \"permission\"\n\t| \"structured-input\"\n\t| \"report-preview\"\n\t| \"loadout\";\n\nexport type OmkOwnedDomain =\n\t| \"ontology\"\n\t| \"search\"\n\t| \"memory\"\n\t| \"cache\"\n\t| \"compaction\"\n\t| \"multi-agent\"\n\t| \"session\"\n\t| \"scheduler\";\n\nexport type CompositionVerdict = \"admit\" | \"reject\" | \"defer\" | \"canary\";\n\nexport interface CompositionResourceFilter {\n\textensions: boolean;\n\tskills: boolean;\n\tprompts: boolean;\n\tthemes: boolean;\n}\n\nexport interface SurfaceOwnerRule {\n\tsurface: CompositionSurface;\n\townerPackageIdentity: string;\n}\n\nexport interface PackageCompositionPolicy {\n\treadonly omkOwnedDomains: readonly OmkOwnedDomain[];\n\treadonly surfaceOwnership: readonly SurfaceOwnerRule[];\n\treadonly allowedResources: Readonly<Record<string, Partial<CompositionResourceFilter>>>;\n\treadonly capabilityToSurfaces: Readonly<Record<string, readonly CompositionSurface[]>>;\n\treadonly capabilityToOmkDomains: Readonly<Record<string, readonly OmkOwnedDomain[]>>;\n}\n\nexport interface CompositionInput {\n\tidentity: string;\n\treview: ProcurementReview;\n\trequestedSurfaces?: readonly CompositionSurface[];\n}\n\nexport interface CompositionConflict {\n\tkind:\n\t\t| \"duplicate-surface-owner\"\n\t\t| \"omk-domain-mutation\"\n\t\t| \"unapproved-surface\"\n\t\t| \"capability-surface-mismatch\"\n\t\t| \"resource-filter-blocked\";\n\tsurface?: CompositionSurface;\n\tdomain?: OmkOwnedDomain;\n\towner?: string;\n\tcapability?: string;\n\treason: string;\n}\n\nexport interface CompositionReview {\n\tidentity: string;\n\tverdict: CompositionVerdict;\n\tallowedResources: CompositionResourceFilter;\n\tadmittedSurfaces: CompositionSurface[];\n\tconflicts: CompositionConflict[];\n\tdeferredReason?: string;\n\trejectedReasons: string[];\n}\n\nexport interface CompositionPromotionRecord {\n\tschemaVersion: \"omk.package-composition.promotion.v1\";\n\tidentity: string;\n\tsource: string;\n\tscope: \"project\";\n\tallowedResources: CompositionResourceFilter;\n\tadmittedSurfaces: CompositionSurface[];\n\treviewedAt: string;\n\treviewedBy: \"manual\" | \"root-orchestrator\";\n}\n\nconst ALL_RESOURCES: CompositionResourceFilter = {\n\textensions: true,\n\tskills: true,\n\tprompts: true,\n\tthemes: true,\n};\n\nconst SIDE_EFFECT_CAPABILITIES = new Set([\n\t\"child-process\",\n\t\"network\",\n\t\"filesystem-write\",\n\t\"browser-control\",\n\t\"telemetry\",\n]);\n\nconst RESOURCE_PATTERNS: Record<keyof CompositionResourceFilter, string[]> = {\n\textensions: [\"**/*\"],\n\tskills: [\"**/*\"],\n\tprompts: [\"**/*\"],\n\tthemes: [\"**/*\"],\n};\n\nexport function createDefaultCompositionPolicy(): PackageCompositionPolicy {\n\treturn {\n\t\tomkOwnedDomains: [\"ontology\", \"search\", \"memory\", \"cache\", \"compaction\", \"multi-agent\", \"session\", \"scheduler\"],\n\t\tsurfaceOwnership: [\n\t\t\t{ surface: \"theme\", ownerPackageIdentity: \"npm:pi-tokyo-night\" },\n\t\t\t{ surface: \"footer\", ownerPackageIdentity: \"npm:pi-zentui\" },\n\t\t\t{ surface: \"editor\", ownerPackageIdentity: \"npm:pi-zentui\" },\n\t\t\t{ surface: \"header\", ownerPackageIdentity: \"omk:core\" },\n\t\t\t{ surface: \"tool-row\", ownerPackageIdentity: \"npm:pi-claude-style-tools\" },\n\t\t\t{ surface: \"loadout\", ownerPackageIdentity: \"npm:pi-loadout\" },\n\t\t\t{ surface: \"permission\", ownerPackageIdentity: \"npm:@gotgenes/pi-permission-system\" },\n\t\t\t{ surface: \"structured-input\", ownerPackageIdentity: \"npm:@juicesharp/rpiv-ask-user-question\" },\n\t\t\t{ surface: \"report-preview\", ownerPackageIdentity: \"npm:pi-markdown-preview\" },\n\t\t],\n\t\tallowedResources: {\n\t\t\t\"npm:pi-tokyo-night\": { extensions: false, skills: false, prompts: false, themes: true },\n\t\t\t\"npm:pi-zentui\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:pi-claude-style-tools\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:pi-loadout\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:pi-lens\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:@gotgenes/pi-permission-system\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:@juicesharp/rpiv-ask-user-question\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:pi-markdown-preview\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:pi-langfuse\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:pi-cache-optimizer\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t\t\"npm:pi-sandbox\": { extensions: true, skills: false, prompts: false, themes: false },\n\t\t},\n\t\tcapabilityToSurfaces: {\n\t\t\tsetFooter: [\"footer\"],\n\t\t\tsetEditorComponent: [\"editor\"],\n\t\t\tsetHeader: [\"header\"],\n\t\t\tsetStatus: [\"status\"],\n\t\t\trenderCall: [\"tool-row\"],\n\t\t\trenderResult: [\"tool-row\"],\n\t\t\tregisterMessageRenderer: [\"assistant-markdown\"],\n\t\t\tsetActiveTools: [\"loadout\"],\n\t\t\tpermission: [\"permission\"],\n\t\t\taskUserQuestion: [\"structured-input\"],\n\t\t\tmarkdownPreview: [\"report-preview\"],\n\t\t},\n\t\tcapabilityToOmkDomains: {\n\t\t\tcontext: [\"session\"],\n\t\t\tbefore_provider_request: [\"cache\", \"session\"],\n\t\t\tsession_before_compact: [\"compaction\"],\n\t\t\tsetModel: [\"session\"],\n\t\t\tsetThinkingLevel: [\"session\"],\n\t\t\tmemory: [\"memory\"],\n\t\t\tcache: [\"cache\"],\n\t\t\tontology: [\"ontology\"],\n\t\t\tmultiAgent: [\"multi-agent\"],\n\t\t\tscheduler: [\"scheduler\"],\n\t\t},\n\t};\n}\n\nexport function checkSingleSurfaceOwner(\n\tidentity: string,\n\trequestedSurfaces: readonly CompositionSurface[],\n\texistingOwners: readonly SurfaceOwnerRule[],\n): CompositionConflict[] {\n\tconst key = packageIdentityKey(identity);\n\tconst conflicts: CompositionConflict[] = [];\n\tfor (const surface of uniqueSorted(requestedSurfaces)) {\n\t\tconst owner = existingOwners.find((rule) => rule.surface === surface);\n\t\tif (!owner) continue;\n\t\tif (owner.ownerPackageIdentity === key || owner.ownerPackageIdentity === identity) continue;\n\t\tconflicts.push({\n\t\t\tkind: \"duplicate-surface-owner\",\n\t\t\tsurface,\n\t\t\towner: owner.ownerPackageIdentity,\n\t\t\treason: `${identity} cannot claim ${surface}; ${owner.ownerPackageIdentity} already owns it`,\n\t\t});\n\t}\n\treturn conflicts;\n}\n\nexport function checkOmkDomainMutation(\n\tidentity: string,\n\tcapabilities: readonly string[],\n\tpolicy: PackageCompositionPolicy,\n): CompositionConflict[] {\n\tconst conflicts: CompositionConflict[] = [];\n\tfor (const capability of capabilities) {\n\t\tconst domains = policy.capabilityToOmkDomains[capability] ?? [];\n\t\tfor (const domain of domains) {\n\t\t\tconflicts.push({\n\t\t\t\tkind: \"omk-domain-mutation\",\n\t\t\t\tdomain,\n\t\t\t\tcapability,\n\t\t\t\treason: `${identity} requested ${capability}, which mutates OMK-owned ${domain}`,\n\t\t\t});\n\t\t}\n\t}\n\treturn conflicts;\n}\n\nexport function checkCapabilitySurfaceMatch(\n\tidentity: string,\n\trequestedSurfaces: readonly CompositionSurface[],\n\tcapabilities: readonly string[],\n\tpolicy: PackageCompositionPolicy,\n): CompositionConflict[] {\n\tif (capabilities.length === 0) return [];\n\tconst supported = new Set<CompositionSurface>();\n\tfor (const capability of capabilities) {\n\t\tfor (const surface of policy.capabilityToSurfaces[capability] ?? []) {\n\t\t\tsupported.add(surface);\n\t\t}\n\t}\n\n\treturn uniqueSorted(requestedSurfaces)\n\t\t.filter((surface) => !supported.has(surface))\n\t\t.map((surface) => ({\n\t\t\tkind: \"capability-surface-mismatch\" as const,\n\t\t\tsurface,\n\t\t\treason: `${identity} requested ${surface}, but no detected capability supports that surface`,\n\t\t}));\n}\n\nexport function resolveResourceFilter(identity: string, policy: PackageCompositionPolicy): CompositionResourceFilter {\n\tconst override = policy.allowedResources[identity] ?? policy.allowedResources[packageIdentityKey(identity)] ?? {};\n\treturn { ...ALL_RESOURCES, ...override };\n}\n\nexport function inferRequestedSurfaces(\n\treview: ProcurementReview,\n\tpolicy: PackageCompositionPolicy,\n): CompositionSurface[] {\n\tconst surfaces = new Set<CompositionSurface>();\n\tfor (const resource of review.candidate.expectedResources) {\n\t\tif (resource === \"theme\") surfaces.add(\"theme\");\n\t}\n\tfor (const capability of review.capabilities) {\n\t\tfor (const surface of policy.capabilityToSurfaces[capability] ?? []) {\n\t\t\tsurfaces.add(surface);\n\t\t}\n\t}\n\treturn uniqueSorted([...surfaces]);\n}\n\nexport function composePackage(input: CompositionInput, policy: PackageCompositionPolicy): CompositionReview {\n\tconst requestedSurfaces = uniqueSorted(input.requestedSurfaces ?? inferRequestedSurfaces(input.review, policy));\n\tconst allowedResources = resolveResourceFilter(input.identity, policy);\n\tconst conflicts = [\n\t\t...checkSingleSurfaceOwner(input.identity, requestedSurfaces, policy.surfaceOwnership),\n\t\t...checkOmkDomainMutation(input.identity, input.review.capabilities, policy),\n\t\t...checkCapabilitySurfaceMatch(input.identity, requestedSurfaces, input.review.capabilities, policy),\n\t\t...checkResourceFilter(input.identity, requestedSurfaces, allowedResources),\n\t];\n\n\tconst rejectedReasons = [...input.review.rejectedReasons, ...conflicts.map((conflict) => conflict.reason)];\n\tconst blockingConflict = conflicts.find((conflict) =>\n\t\t[\n\t\t\t\"duplicate-surface-owner\",\n\t\t\t\"omk-domain-mutation\",\n\t\t\t\"unapproved-surface\",\n\t\t\t\"capability-surface-mismatch\",\n\t\t\t\"resource-filter-blocked\",\n\t\t].includes(conflict.kind),\n\t);\n\n\tif (!input.review.pinned) {\n\t\treturn compositionReview(input.identity, \"reject\", allowedResources, requestedSurfaces, conflicts, undefined, [\n\t\t\t...rejectedReasons,\n\t\t\t\"missing-exact-pin\",\n\t\t]);\n\t}\n\tif (input.review.licenseVerdict === \"reject\" || input.review.lifecycleVerdict === \"reject\") {\n\t\treturn compositionReview(\n\t\t\tinput.identity,\n\t\t\t\"reject\",\n\t\t\tallowedResources,\n\t\t\trequestedSurfaces,\n\t\t\tconflicts,\n\t\t\tundefined,\n\t\t\trejectedReasons,\n\t\t);\n\t}\n\tif (input.review.pathCompatibility === \"pi-hardcoded\") {\n\t\treturn compositionReview(input.identity, \"reject\", allowedResources, requestedSurfaces, conflicts, undefined, [\n\t\t\t...rejectedReasons,\n\t\t\t\"pi-hardcoded-paths\",\n\t\t]);\n\t}\n\tif (blockingConflict) {\n\t\treturn compositionReview(\n\t\t\tinput.identity,\n\t\t\t\"reject\",\n\t\t\tallowedResources,\n\t\t\trequestedSurfaces,\n\t\t\tconflicts,\n\t\t\tundefined,\n\t\t\trejectedReasons,\n\t\t);\n\t}\n\tif (input.review.adoption === \"deferred\") {\n\t\treturn compositionReview(\n\t\t\tinput.identity,\n\t\t\t\"defer\",\n\t\t\tallowedResources,\n\t\t\trequestedSurfaces,\n\t\t\tconflicts,\n\t\t\tinput.review.deferredReason,\n\t\t\trejectedReasons,\n\t\t);\n\t}\n\tif (input.review.adoption === \"reject\") {\n\t\treturn compositionReview(\n\t\t\tinput.identity,\n\t\t\t\"reject\",\n\t\t\tallowedResources,\n\t\t\trequestedSurfaces,\n\t\t\tconflicts,\n\t\t\tundefined,\n\t\t\trejectedReasons,\n\t\t);\n\t}\n\n\tconst canaryReasons = canaryRequiredReasons(input.review.capabilities);\n\tif (input.review.risk === \"high\" && canaryReasons.length === 0) {\n\t\tcanaryReasons.push(\"canary-required: high-risk\");\n\t}\n\tif (canaryReasons.length > 0) {\n\t\treturn compositionReview(input.identity, \"canary\", allowedResources, requestedSurfaces, conflicts, undefined, [\n\t\t\t...rejectedReasons,\n\t\t\t...canaryReasons,\n\t\t]);\n\t}\n\n\treturn compositionReview(\n\t\tinput.identity,\n\t\t\"admit\",\n\t\tallowedResources,\n\t\trequestedSurfaces,\n\t\tconflicts,\n\t\tundefined,\n\t\trejectedReasons,\n\t);\n}\n\nexport function composeCandidateBatch(\n\tinputs: readonly CompositionInput[],\n\tbasePolicy: PackageCompositionPolicy,\n): CompositionReview[] {\n\tconst owners = [...basePolicy.surfaceOwnership];\n\tconst results: CompositionReview[] = [];\n\tfor (const input of inputs) {\n\t\tconst policy = { ...basePolicy, surfaceOwnership: owners };\n\t\tconst result = composePackage(input, policy);\n\t\tresults.push(result);\n\t\tif (result.verdict === \"admit\" || result.verdict === \"canary\") {\n\t\t\tconst ownerKey = packageIdentityKey(result.identity);\n\t\t\tfor (const surface of result.admittedSurfaces) {\n\t\t\t\tif (!owners.some((owner) => owner.surface === surface)) {\n\t\t\t\t\towners.push({ surface, ownerPackageIdentity: ownerKey });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\treturn results;\n}\n\nexport function toPackageSource(review: CompositionReview): PackageSource {\n\tassertPromotable(review);\n\tif (isAllResourcesEnabled(review.allowedResources)) {\n\t\treturn review.identity;\n\t}\n\treturn {\n\t\tsource: review.identity,\n\t\textensions: review.allowedResources.extensions ? RESOURCE_PATTERNS.extensions : [],\n\t\tskills: review.allowedResources.skills ? RESOURCE_PATTERNS.skills : [],\n\t\tprompts: review.allowedResources.prompts ? RESOURCE_PATTERNS.prompts : [],\n\t\tthemes: review.allowedResources.themes ? RESOURCE_PATTERNS.themes : [],\n\t};\n}\n\nexport function createPromotionRecord(\n\treview: CompositionReview,\n\tsource: string,\n\toptions: { reviewedBy?: \"manual\" | \"root-orchestrator\"; now?: Date } = {},\n): CompositionPromotionRecord {\n\tassertPromotable(review);\n\treturn {\n\t\tschemaVersion: \"omk.package-composition.promotion.v1\",\n\t\tidentity: review.identity,\n\t\tsource: redactSource(source),\n\t\tscope: \"project\",\n\t\tallowedResources: review.allowedResources,\n\t\tadmittedSurfaces: review.admittedSurfaces,\n\t\treviewedAt: (options.now ?? new Date()).toISOString(),\n\t\treviewedBy: options.reviewedBy ?? \"root-orchestrator\",\n\t};\n}\n\nfunction checkResourceFilter(\n\tidentity: string,\n\trequestedSurfaces: readonly CompositionSurface[],\n\tfilter: CompositionResourceFilter,\n): CompositionConflict[] {\n\tconst conflicts: CompositionConflict[] = [];\n\tfor (const surface of requestedSurfaces) {\n\t\tconst resource = resourceForSurface(surface);\n\t\tif (filter[resource]) continue;\n\t\tconflicts.push({\n\t\t\tkind: \"resource-filter-blocked\",\n\t\t\tsurface,\n\t\t\treason: `${identity} requested ${surface}, but ${resource} resources are disabled`,\n\t\t});\n\t}\n\treturn conflicts;\n}\n\nfunction resourceForSurface(surface: CompositionSurface): keyof CompositionResourceFilter {\n\treturn surface === \"theme\" ? \"themes\" : \"extensions\";\n}\n\nfunction canaryRequiredReasons(capabilities: readonly string[]): string[] {\n\tconst reasons: string[] = [];\n\tfor (const capability of capabilities) {\n\t\tif (SIDE_EFFECT_CAPABILITIES.has(capability)) {\n\t\t\treasons.push(`canary-required: ${capability}`);\n\t\t}\n\t}\n\treturn uniqueSorted(reasons);\n}\n\nfunction compositionReview(\n\tidentity: string,\n\tverdict: CompositionVerdict,\n\tallowedResources: CompositionResourceFilter,\n\tadmittedSurfaces: readonly CompositionSurface[],\n\tconflicts: readonly CompositionConflict[],\n\tdeferredReason: string | undefined,\n\trejectedReasons: readonly string[],\n): CompositionReview {\n\treturn {\n\t\tidentity,\n\t\tverdict,\n\t\tallowedResources,\n\t\tadmittedSurfaces: uniqueSorted(admittedSurfaces),\n\t\tconflicts: [...conflicts],\n\t\t...(deferredReason === undefined ? {} : { deferredReason }),\n\t\trejectedReasons: uniqueSorted(rejectedReasons),\n\t};\n}\n\nfunction assertPromotable(review: CompositionReview): void {\n\tif (review.verdict !== \"admit\") {\n\t\tthrow new Error(`Package composition verdict ${review.verdict} cannot be promoted`);\n\t}\n}\n\nfunction isAllResourcesEnabled(filter: CompositionResourceFilter): boolean {\n\treturn filter.extensions && filter.skills && filter.prompts && filter.themes;\n}\n\nfunction packageIdentityKey(identity: string): string {\n\tif (!identity.startsWith(\"npm:\")) return identity;\n\tconst spec = identity.slice(\"npm:\".length);\n\tconst at = spec.lastIndexOf(\"@\");\n\tif (at <= 0) return identity;\n\tif (spec.startsWith(\"@\")) {\n\t\tconst scopedVersionAt = spec.indexOf(\"@\", spec.indexOf(\"/\") + 1);\n\t\treturn scopedVersionAt > 0 ? `npm:${spec.slice(0, scopedVersionAt)}` : identity;\n\t}\n\treturn `npm:${spec.slice(0, at)}`;\n}\n\nfunction uniqueSorted<T extends string>(values: readonly T[]): T[] {\n\treturn [...new Set(values)].sort();\n}\n\nfunction redactSource(source: string): string {\n\treturn source\n\t\t.replace(/(https?:\\/\\/)([^\\s/@]+@)/gi, \"$1<redacted>@\")\n\t\t.replace(/([?&](?:access_token|auth|key|password|token)=)[^&#]+/gi, \"$1<redacted>\");\n}\n"]}