kibi-cli 2.1.0 → 2.3.0

package/dist/operations/modeling/model-requirement.js

@@ -1,11 +1,167 @@
-import { buildStrictWriteSet } from "../../public/check-types.js";
+import { buildStrictWriteSet, } from "../../public/check-types.js";
 import { readKbManifestStatus } from "../../utils/kb-manifest.js";
+import { isConventionalSubjectKey, normalizeSubjectKey, } from "../../utils/strict-modeling.js";
 import { normalizeSemanticClause, semanticClaimKey, } from "../semantic-advisor/clauses.js";
 import { semanticSourceHash } from "../semantic-advisor/shared.js";
 import { buildLogicApplyPlan } from "./logic-modeling.js";
 import { strictWriteSetToApplyPlan, writeSetPrimaryEntityId, } from "./requirement-applyplan.js";
 import { estimateNormativeSignalConfidence, extractRequirementClaim, } from "./requirement-modeler.js";
 import { normalizeOptionalString, normalizeSourceFiles, } from "./requirement-utils.js";
+import { alignRequirementVocabulary, } from "./vocabulary-alignment.js";
+const NEW_SUBJECT_REVIEW_SCORE = 0.3;
+function reuseExistingSubject(writeSet, existingFactId) {
+    if (!writeSet.isStrict)
+        return { writeSet, replacedSubjectId: null };
+    const replacedSubjectId = writeSet.subjectFact.id;
+    return {
+        replacedSubjectId,
+        writeSet: {
+            ...writeSet,
+            subjectFact: {
+                ...writeSet.subjectFact,
+                id: existingFactId,
+                properties: { ...writeSet.subjectFact.properties, id: existingFactId },
+            },
+            relationships: writeSet.relationships.map((relationship) => relationship.type === "constrains"
+                ? { ...relationship, to: existingFactId }
+                : relationship),
+        },
+    };
+}
+function possibleDuplicateObservation(claimKey, statement, source, candidates) {
+    const id = `FACT-OBS-POSSIBLE-DUPLICATE-${claimKey.replace(/^CLAIM-/, "")}`;
+    return {
+        type: "fact",
+        id,
+        properties: {
+            id,
+            title: `Possible duplicate: ${statement}`,
+            status: "active",
+            source,
+            fact_kind: "observation",
+            tags: ["review:possible-duplicate", "vocabulary-alignment"],
+        },
+        relationships: candidates.map((candidate) => ({
+            type: "relates_to",
+            from: id,
+            to: candidate.factId,
+        })),
+    };
+}
+/**
+ * Resolve the clause subject against the existing KB vocabulary. A heuristic
+ * subject converges onto the chosen existing subject; an explicitly provided
+ * subject is kept (the caller owns it) but reuses the existing subject fact
+ * when the keys match. Otherwise the plan explicitly declares a new subject.
+ */
+// implements REQ-kibi-subject-vocabulary
+async function applyVocabularyAlignment(context, extracted, claimKey) {
+    const initial = buildStrictWriteSet({
+        claim: extracted.claim,
+        statement: extracted.statement,
+    });
+    const unchanged = {
+        writeSet: initial,
+        outcome: null,
+        warnings: [],
+        reviewPlan: [],
+        adjustPlan: (plan) => plan,
+    };
+    if (!context?.prolog || !initial.isStrict)
+        return unchanged;
+    const proposedSubjectKey = normalizeSubjectKey(extracted.claim.subjectKey);
+    const outcome = await alignRequirementVocabulary(context, {
+        claimKey,
+        statement: extracted.statement,
+        proposedSubjectKey,
+    });
+    if (outcome === null)
+        return unchanged;
+    const warnings = [];
+    let writeSet = initial;
+    let replacedSubjectId = null;
+    const subject = outcome.subject;
+    if (subject.decision === "reuse_existing" && subject.existingFactId) {
+        const followsVocabulary = extracted.extractionMode !== "provided" ||
+            proposedSubjectKey === subject.subjectKey;
+        if (followsVocabulary) {
+            const rebuilt = buildStrictWriteSet({
+                claim: { ...extracted.claim, subjectKey: subject.subjectKey },
+                statement: extracted.statement,
+            });
+            ({ writeSet, replacedSubjectId } = reuseExistingSubject(rebuilt, subject.existingFactId));
+        }
+        else {
+            warnings.push({
+                kind: "subject_reuse_review",
+                message: `Provided subjectKey ${proposedSubjectKey} is new, but existing subject ${subject.subjectKey} (${subject.existingFactId}) matches this clause.`,
+                nextAction: `Reuse subjectKey ${subject.subjectKey} so this requirement can be compared with the others on that subject, or keep ${proposedSubjectKey} if it is genuinely a different component.`,
+            });
+        }
+    }
+    else {
+        if (!isConventionalSubjectKey(subject.subjectKey)) {
+            warnings.push({
+                kind: "subject_key_shape_review",
+                message: `New subject key ${subject.subjectKey} does not follow the component.aspect[.sub] convention checked by subject-key-shape.`,
+                nextAction: "Pass subjectKey as a dotted key with lowercase snake segments (for example kibi.cli.gc) so later requirements about the same component can reuse it.",
+            });
+        }
+        const nearest = subject.candidates[0];
+        if (nearest && nearest.score >= NEW_SUBJECT_REVIEW_SCORE) {
+            warnings.push({
+                kind: "new_subject_declared",
+                message: `Declaring new subject ${subject.subjectKey}; nearest existing subject is ${nearest.subjectKey} (score ${nearest.score}).`,
+                nextAction: "Confirm the new subject is a different component, or pass subjectKey set to the existing subject to reuse it.",
+            });
+        }
+    }
+    const reviewPlan = outcome.redundancyCandidates.length > 0
+        ? [
+            possibleDuplicateObservation(claimKey, extracted.statement, extracted.source, outcome.redundancyCandidates),
+        ]
+        : [];
+    if (outcome.redundancyCandidates.length > 0) {
+        warnings.push({
+            kind: "possible_duplicate",
+            message: `This clause may restate existing claim(s) ${outcome.redundancyCandidates
+                .map((candidate) => candidate.factId)
+                .join(", ")} on ${subject.subjectKey}.`,
+            nextAction: "Review the candidates: reuse the existing fact, supersede or restate the existing requirement, or record the returned review:possible-duplicate observation. This is advice, not a check verdict.",
+        });
+    }
+    const declaredNew = subject.decision === "declare_new";
+    return {
+        writeSet,
+        outcome,
+        warnings,
+        reviewPlan,
+        adjustPlan: (plan) => plan
+            .filter((step) => !(replacedSubjectId !== null &&
+            writeSet.isStrict &&
+            step.id === writeSet.subjectFact.id &&
+            step.type === "fact" &&
+            step.properties
+                ?.fact_kind === "subject"))
+            .map((step) => {
+            if (!declaredNew ||
+                step.type !== "fact" ||
+                step.properties
+                    ?.fact_kind !== "subject") {
+                return step;
+            }
+            const properties = step.properties;
+            const tags = Array.isArray(properties.tags) ? properties.tags : [];
+            return {
+                ...step,
+                properties: {
+                    ...properties,
+                    tags: [...tags, "vocabulary:new-subject"],
+                },
+            };
+        }),
+    };
+}
 export { estimateNormativeSignalConfidence, extractRequirementClaim, strictWriteSetToApplyPlan, writeSetPrimaryEntityId, };
 // implements REQ-kibi-logical-requirement-coverage
 // covered_by TEST-kibi-logical-requirement-coverage
@@ -61,7 +217,7 @@ export async function getWorkspaceMigrationWarning(workspaceRoot) {
         return null;
     return status.warning;
 }
-export async function handleKbModelRequirement(_prolog, args, workspaceRoot) {
+export async function handleKbModelRequirement(_prolog, args, workspaceRoot, context) {
     const extracted = extractRequirementClaim({
         ...args,
         source: normalizeOptionalString(args.source) ??
@@ -123,20 +279,20 @@ export async function handleKbModelRequirement(_prolog, args, workspaceRoot) {
             migrationWarning,
         };
     }
-    const writeSet = buildStrictWriteSet({
-        claim: extracted.claim,
-        statement: extracted.statement,
-    });
     const claimKey = semanticClaimKey(extracted.statement);
+    const aligned = await applyVocabularyAlignment(context, extracted, claimKey);
+    const writeSet = aligned.writeSet;
     const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
-    const applyPlan = strictWriteSetToApplyPlan(writeSet).map((step) => annotateModelRequirementStep(step, {
+    const applyPlan = aligned
+        .adjustPlan(strictWriteSetToApplyPlan(writeSet))
+        .map((step) => annotateModelRequirementStep(step, {
         claimKey,
         statement: extracted.statement,
         logicClaims,
     }));
     const migrationWarning = await getWorkspaceMigrationWarning(workspaceRoot);
     const warnings = writeSet.isStrict
-        ? []
+        ? [...aligned.warnings]
         : [
             {
                 kind: "low_confidence_observation_downgrade",
@@ -162,6 +318,14 @@ export async function handleKbModelRequirement(_prolog, args, workspaceRoot) {
         extractionWarnings: extracted.extractionWarnings,
         warnings,
         migrationWarning,
+        ...(aligned.outcome !== null
+            ? {
+                vocabularyAlignment: {
+                    ...aligned.outcome,
+                    reviewPlan: aligned.reviewPlan,
+                },
+            }
+            : {}),
     };
     return {
         content: [
@@ -182,6 +346,8 @@ export async function executeModelRequirement(args, context) {
     // kb_model_requirement is intentionally off the external semantic-classifier
     // allowlist: classification after modeling only produced provenance warnings
     // and is not worth a metered provider call. Use kb_semantic_advisor when
-    // classifier routing is needed.
-    return handleKbModelRequirement(context.prolog, args, context.workspaceRoot);
+    // classifier routing is needed. It is on the vocabulary-alignment allowlist:
+    // choosing an existing subject is exactly the modeling-time decision that
+    // provider is for, and it only runs when explicitly activated.
+    return handleKbModelRequirement(context.prolog, args, context.workspaceRoot, context);
 }

package/dist/operations/modeling/predicate-applyplan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAI9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA,mBAAmB,CA6ErB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqChC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAwBhC;AAGD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+BhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}
+{"version":3,"file":"predicate-applyplan.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-applyplan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,sBAAsB,CAAC;AAQ9B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,EAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,gBAAgB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EACvD,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,EAChC,WAAW,CAAC,EAAE;IACZ,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA,mBAAmB,CA8FrB;AAGD,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqChC;AAGD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,GAAE,SAAS,MAAM,EAAO,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAwBhC;AAGD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+BhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,0BAA0B,CAoE5B"}

package/dist/operations/modeling/predicate-applyplan.js

@@ -4,16 +4,27 @@ import { aggregateBindingProvenance, bindingCanBeApplied, classifyBinding, isGen
 import { inferArgs } from "./predicate-inference.js";
 import { schemaForCandidate } from "./predicate-loader.js";
 import { hashId } from "./predicate-utils.js";
+import { applyArgumentRewrites, predicateArgumentConformance, } from "./predicate-vocabulary.js";
 // implements REQ-mcp-suggest-predicates
 export function buildSuggestion(schema, text, subject, score, argumentBindings = {}, polarityHint, diagnostics) {
     const inferredArgs = inferArgs(schema, text, subject);
     const canonicalLauncherArgs = exactLauncherPredicateArgs(schema.predicate_name, text);
-    const predicateArgs = schema.argument_names.map((name, index) => {
+    const boundArgs = schema.argument_names.map((name, index) => {
         const exactBinding = argumentBindings[name];
         return typeof exactBinding === "string" && exactBinding.trim().length > 0
             ? exactBinding.trim()
             : (inferredArgs[index] ?? "unknown");
     });
+    // A schema with closed argument vocabularies only accepts its declared
+    // constants: aliases converge onto the constant, anything else stays
+    // unbound so the plan asks for a declared value instead of minting an atom.
+    const vocabulary = {
+        constants: schema.argument_constants ?? {},
+        aliases: schema.argument_aliases ?? {},
+    };
+    const conformance = predicateArgumentConformance(schema.argument_names, boundArgs, vocabulary);
+    const predicateArgs = applyArgumentRewrites(boundArgs, conformance.rewrites);
+    const undeclaredArguments = new Set(conformance.undeclared.map((value) => value.argumentName));
     const bindingProvenanceByArgument = Object.fromEntries(schema.argument_names.map((name, index) => [
         name,
         classifyBinding(predicateArgs[index] ?? "unknown", text, (typeof argumentBindings[name] === "string" &&
@@ -25,7 +36,8 @@ export function buildSuggestion(schema, text, subject, score, argumentBindings =
                 typeof argumentBindings[name] !== "string")),
     ]));
     const bindingProvenance = aggregateBindingProvenance(Object.values(bindingProvenanceByArgument));
-    const unboundArguments = schema.argument_names.filter((name) => !bindingCanBeApplied(bindingProvenanceByArgument[name] ?? "placeholder"));
+    const unboundArguments = schema.argument_names.filter((name) => undeclaredArguments.has(name) ||
+        !bindingCanBeApplied(bindingProvenanceByArgument[name] ?? "placeholder"));
     const canonicalKey = `${schema.predicate_name}(${predicateArgs.join(",")})`;
     // Permission-style inference carries the deontic decision as its final
     // argument. Preserve that polarity in the typed suggestion instead of

package/dist/operations/modeling/predicate-inference-1.js

@@ -1,7 +1,7 @@
 import { normalizePredicateToken, normalizeSubjectKey, singularize, slug, } from "./predicate-utils.js";
 // implements REQ-mcp-suggest-predicates
 export function inferPermissionRuleArgs(text) {
-    const prohibition = text.match(/^(?<actor>[a-z][a-z\s_-]*?)\s+(?:must\s+not|cannot|can't|is\s+forbidden\s+to)\s+(?<action>[a-z][a-z_-]*)\s+(?<resource>.+?)\.?$/i);
+    const prohibition = text.match(/^(?<actor>[a-z][a-z\s_-]*?)\s+(?:must\s+not|must\s+never|never|cannot|can't|is\s+forbidden\s+to)\s+(?<action>[a-z][a-z_-]*)\s+(?<resource>.+?)\.?$/i);
     if (prohibition?.groups) {
         return [
             singularize(slug(prohibition.groups.actor ?? "actor")),

package/dist/operations/modeling/predicate-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-loader.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAK3E,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAG9B,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAExE;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CACxE,wBAAwB,EACxB,UAAU,CACX,GAAG;IACF,WAAW,EAAE,mBAAmB,CAAC;CAClC,CAsBA;AAGD,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,sBAAsB,EAAE,OAAO,EAC/B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAwBrC;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,wBAAwB,EAAE,CAmC5B;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,mBAAmB,GAAG,SAAS,CAOjC;AAGD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAQpD"}
+{"version":3,"file":"predicate-loader.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAK3E,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAI9B,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAExE;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CACxE,wBAAwB,EACxB,UAAU,CACX,GAAG;IACF,WAAW,EAAE,mBAAmB,CAAC;CAClC,CA4BA;AAGD,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,sBAAsB,EAAE,OAAO,EAC/B,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAwBrC;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,wBAAwB,EAAE,CAwD5B;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,mBAAmB,GAAG,SAAS,CAOjC;AAGD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAQpD"}

package/dist/operations/modeling/predicate-loader.js

@@ -1,6 +1,7 @@
 import { parseEntityFromList, parseListOfLists } from "../../prolog/codec.js";
 import { DEFAULT_USAGE_HINTS, USAGE_HINTS_BY_PREDICATE, } from "./predicate-catalog.js";
 import { hashId, normalizeOptionalString } from "./predicate-utils.js";
+import { predicateVocabularyFromEntity } from "./predicate-vocabulary.js";
 export function optionalPredicateName(value) {
     return typeof value === "string" ? value : undefined;
 }
@@ -16,6 +17,12 @@ export function schemaForCandidate(schema) {
         ...(schema.argument_descriptions
             ? { argument_descriptions: schema.argument_descriptions }
             : {}),
+        ...(schema.argument_constants
+            ? { argument_constants: schema.argument_constants }
+            : {}),
+        ...(schema.argument_aliases
+            ? { argument_aliases: schema.argument_aliases }
+            : {}),
         ...(schema.aliases ? { aliases: schema.aliases } : {}),
         ...(schema.paraphrase_templates
             ? { paraphrase_templates: schema.paraphrase_templates }
@@ -57,6 +64,7 @@ export function predicateSchemaFromEntity(entity) {
         return [];
     const usageHints = usageHintsFromEntity(entity);
     const argumentDescriptions = stringArray(entity.argument_descriptions);
+    const vocabulary = predicateVocabularyFromEntity(entity);
     return [
         {
             id: String(entity.id ?? hashId("FACT-SCHEMA", [predicateName])),
@@ -69,6 +77,22 @@ export function predicateSchemaFromEntity(entity) {
             ...(argumentDescriptions.length > 0
                 ? { argument_descriptions: argumentDescriptions }
                 : {}),
+            ...(Object.keys(vocabulary.constants).length > 0
+                ? {
+                    argument_constants: Object.fromEntries(Object.entries(vocabulary.constants).map(([name, values]) => [
+                        name,
+                        [...values],
+                    ])),
+                }
+                : {}),
+            ...(Object.keys(vocabulary.aliases).length > 0
+                ? {
+                    argument_aliases: Object.fromEntries(Object.entries(vocabulary.aliases).map(([name, mapping]) => [
+                        name,
+                        { ...mapping },
+                    ])),
+                }
+                : {}),
             keywords: [
                 predicateName,
                 ...stringArray(entity.aliases),

package/dist/operations/modeling/predicate-types.d.ts

@@ -12,6 +12,10 @@ export interface PredicateSchemaCandidate {
     argument_types: string[];
     /** Optional human-readable descriptions aligned with argument_names. */
     argument_descriptions?: string[];
+    /** Closed vocabularies: allowed constants keyed by argument name. */
+    argument_constants?: Record<string, string[]>;
+    /** Legacy spellings keyed by argument name, each mapped to a constant. */
+    argument_aliases?: Record<string, Record<string, string>>;
     keywords: string[];
     /** Human-language aliases and controlled paraphrase templates used for deterministic retrieval. */
     aliases?: string[];

package/dist/operations/modeling/predicate-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-types.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"predicate-types.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-types.ts"],"names":[],"mappings":"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"}

package/dist/operations/modeling/predicate-vocabulary.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Closed argument vocabularies for predicate schemas.
+ *
+ * A `predicate_schema` may declare, per argument name, the constants that
+ * argument accepts (`argument_constants`) and legacy spellings that map onto
+ * one of them (`argument_aliases`). Arguments without an entry stay open.
+ * Declaring constants is what makes paraphrased claims converge: two facts
+ * can only share a ground term when they use the same atoms.
+ */
+export type PredicateVocabulary = Readonly<{
+    constants: Readonly<Record<string, readonly string[]>>;
+    aliases: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}>;
+export type ArgumentRewrite = Readonly<{
+    index: number;
+    argumentName: string;
+    from: string;
+    to: string;
+}>;
+export type UndeclaredArgument = Readonly<{
+    index: number;
+    argumentName: string;
+    value: string;
+    allowed: readonly string[];
+}>;
+export type ArgumentConformance = Readonly<{
+    /** Alias spellings with their declared canonical constant. */
+    rewrites: readonly ArgumentRewrite[];
+    /** Values that are neither a declared constant nor an alias. */
+    undeclared: readonly UndeclaredArgument[];
+}>;
+/**
+ * Read a schema's vocabulary. Malformed entries are ignored here; use
+ * {@link predicateVocabularyErrors} to report them.
+ */
+export declare function predicateVocabularyFromEntity(entity: Readonly<Record<string, unknown>>): PredicateVocabulary;
+export declare function hasPredicateVocabulary(vocabulary: PredicateVocabulary): boolean;
+/**
+ * Cross-field errors in a predicate schema's vocabulary: every key must be an
+ * argument name, aliases need declared constants for their argument, alias
+ * targets must be declared, and an alias may not shadow a constant.
+ */
+export declare function predicateVocabularyErrors(entity: Readonly<Record<string, unknown>>): string[];
+/**
+ * Compare predicate arguments with a schema vocabulary. Open arguments always
+ * conform; an alias is reported as a rewrite, anything else not declared is
+ * reported as undeclared.
+ */
+export declare function predicateArgumentConformance(argumentNames: readonly string[], args: readonly string[], vocabulary: PredicateVocabulary): ArgumentConformance;
+/** Arguments with every alias replaced by its declared constant. */
+export declare function applyArgumentRewrites(args: readonly string[], rewrites: readonly ArgumentRewrite[]): string[];
+/** Canonical key convention shared with predicate apply plans. */
+export declare function predicateCanonicalKey(predicateName: string, args: readonly string[]): string;
+//# sourceMappingURL=predicate-vocabulary.d.ts.map

package/dist/operations/modeling/predicate-vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicate-vocabulary.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-vocabulary.ts"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AAGH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACvD,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;CACrE,CAAC,CAAC;AAGH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC,CAAC;AAGH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,CAAC,CAAC;AAGH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,8DAA8D;IAC9D,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,gEAAgE;IAChE,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC3C,CAAC,CAAC;AAgBH;;;GAGG;AAEH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,mBAAmB,CA0BrB;AAGD,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,mBAAmB,GAC9B,OAAO,CAKT;AAED;;;;GAIG;AAEH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,EAAE,CA+EV;AAED;;;;GAIG;AAEH,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,UAAU,EAAE,mBAAmB,GAC9B,mBAAmB,CAgBrB;AAED,oEAAoE;AAEpE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,MAAM,EAAE,CAIV;AAED,kEAAkE;AAElE,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,CAER"}

package/dist/operations/modeling/predicate-vocabulary.js

@@ -0,0 +1,169 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Structured fields arrive as objects from Markdown or as JSON strings from Prolog. */
+function structuredField(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Read a schema's vocabulary. Malformed entries are ignored here; use
+ * {@link predicateVocabularyErrors} to report them.
+ */
+// implements REQ-kibi-predicate-argument-constants
+export function predicateVocabularyFromEntity(entity) {
+    const rawConstants = structuredField(entity.argument_constants);
+    const rawAliases = structuredField(entity.argument_aliases);
+    const constants = {};
+    if (isRecord(rawConstants)) {
+        for (const [name, values] of Object.entries(rawConstants)) {
+            if (!Array.isArray(values))
+                continue;
+            const strings = values.filter((value) => typeof value === "string" && value.length > 0);
+            if (strings.length > 0)
+                constants[name] = [...new Set(strings)];
+        }
+    }
+    const aliases = {};
+    if (isRecord(rawAliases)) {
+        for (const [name, mapping] of Object.entries(rawAliases)) {
+            if (!isRecord(mapping))
+                continue;
+            const entries = Object.entries(mapping).filter((entry) => typeof entry[1] === "string" && entry[1].length > 0);
+            if (entries.length > 0)
+                aliases[name] = Object.fromEntries(entries);
+        }
+    }
+    return { constants, aliases };
+}
+// implements REQ-kibi-predicate-argument-constants
+export function hasPredicateVocabulary(vocabulary) {
+    return (Object.keys(vocabulary.constants).length > 0 ||
+        Object.keys(vocabulary.aliases).length > 0);
+}
+/**
+ * Cross-field errors in a predicate schema's vocabulary: every key must be an
+ * argument name, aliases need declared constants for their argument, alias
+ * targets must be declared, and an alias may not shadow a constant.
+ */
+// implements REQ-kibi-predicate-argument-constants
+export function predicateVocabularyErrors(entity) {
+    const errors = [];
+    const rawConstants = structuredField(entity.argument_constants);
+    const rawAliases = structuredField(entity.argument_aliases);
+    if (rawConstants === undefined && rawAliases === undefined)
+        return errors;
+    if (entity.fact_kind !== "predicate_schema") {
+        errors.push("argument_constants and argument_aliases are only valid on fact_kind predicate_schema");
+        return errors;
+    }
+    const argumentNames = Array.isArray(entity.argument_names)
+        ? entity.argument_names.filter((name) => typeof name === "string")
+        : [];
+    if (rawConstants !== undefined && !isRecord(rawConstants)) {
+        errors.push("argument_constants must map argument names to constant lists");
+    }
+    if (rawAliases !== undefined && !isRecord(rawAliases)) {
+        errors.push("argument_aliases must map argument names to alias-to-constant objects");
+    }
+    const vocabulary = predicateVocabularyFromEntity(entity);
+    if (isRecord(rawConstants)) {
+        for (const [name, values] of Object.entries(rawConstants)) {
+            if (!argumentNames.includes(name)) {
+                errors.push(`argument_constants.${name} is not one of argument_names (${argumentNames.join(", ")})`);
+            }
+            if (!Array.isArray(values) ||
+                values.length === 0 ||
+                values.some((value) => typeof value !== "string" || value === "")) {
+                errors.push(`argument_constants.${name} must be a non-empty list of non-empty strings`);
+            }
+        }
+    }
+    if (isRecord(rawAliases)) {
+        for (const [name, mapping] of Object.entries(rawAliases)) {
+            if (!argumentNames.includes(name)) {
+                errors.push(`argument_aliases.${name} is not one of argument_names (${argumentNames.join(", ")})`);
+                continue;
+            }
+            const declared = vocabulary.constants[name];
+            if (declared === undefined) {
+                errors.push(`argument_aliases.${name} requires argument_constants.${name} to declare the canonical constants`);
+                continue;
+            }
+            if (!isRecord(mapping)) {
+                errors.push(`argument_aliases.${name} must map alias spellings to constants`);
+                continue;
+            }
+            for (const [alias, target] of Object.entries(mapping)) {
+                if (typeof target !== "string" || !declared.includes(target)) {
+                    errors.push(`argument_aliases.${name}.${alias} must name a declared constant of ${name}`);
+                }
+                if (declared.includes(alias)) {
+                    errors.push(`argument_aliases.${name}.${alias} shadows a declared constant; remove the alias`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Compare predicate arguments with a schema vocabulary. Open arguments always
+ * conform; an alias is reported as a rewrite, anything else not declared is
+ * reported as undeclared.
+ */
+// implements REQ-kibi-predicate-argument-constants
+export function predicateArgumentConformance(argumentNames, args, vocabulary) {
+    const rewrites = [];
+    const undeclared = [];
+    args.forEach((value, index) => {
+        const argumentName = argumentNames[index];
+        if (argumentName === undefined)
+            return;
+        const allowed = vocabulary.constants[argumentName];
+        if (allowed === undefined || allowed.includes(value))
+            return;
+        const canonical = vocabulary.aliases[argumentName]?.[value];
+        if (canonical !== undefined && allowed.includes(canonical)) {
+            rewrites.push({ index, argumentName, from: value, to: canonical });
+            return;
+        }
+        undeclared.push({ index, argumentName, value, allowed });
+    });
+    return { rewrites, undeclared };
+}
+/** Arguments with every alias replaced by its declared constant. */
+// implements REQ-kibi-predicate-argument-constants
+export function applyArgumentRewrites(args, rewrites) {
+    const next = [...args];
+    for (const rewrite of rewrites)
+        next[rewrite.index] = rewrite.to;
+    return next;
+}
+/** Canonical key convention shared with predicate apply plans. */
+// implements REQ-kibi-predicate-argument-constants
+export function predicateCanonicalKey(predicateName, args) {
+    return `${predicateName}(${args.join(",")})`;
+}

package/dist/operations/modeling/requirement-types.d.ts

@@ -1,5 +1,6 @@
 import type { LogicRuleIR } from "../../logic/ir.js";
 import type { SemanticClaim, StrictWriteSet } from "../../public/check-types.js";
+import type { VocabularyAlignmentOutcome } from "./vocabulary-alignment.js";
 export type ModelRequirementArgs = Readonly<Record<string, unknown>> & {
     readonly text: string;
     readonly source?: string;
@@ -46,6 +47,10 @@ export interface ModelRequirementResult {
             nextAction: string;
         }>;
         migrationWarning: string | null;
+        /** Subject reuse decision and possible-duplicate review candidates. */
+        vocabularyAlignment?: VocabularyAlignmentOutcome & {
+            readonly reviewPlan: Array<Record<string, unknown>>;
+        };
         logic?: {
             readonly semanticKey: string;
             readonly claimKey: string;

package/dist/operations/modeling/requirement-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requirement-types.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/requirement-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACf,MAAM,6BAA6B,CAAC;AAGrC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAGF,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,aAAa,CAAC;IACrB,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;IACtD,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAGD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;QACrB,QAAQ,EAAE,cAAc,CAAC;QACzB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1C,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;QACtD,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC,CAAC;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,KAAK,CAAC,EAAE;YACN,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;YAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;YAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;YAChC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;SAClC,CAAC;KACH,CAAC;IACF,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,QAAQ,EAAE,cAAc,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC"}
+{"version":3,"file":"requirement-types.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/requirement-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACf,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAG5E,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAGF,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,aAAa,CAAC;IACrB,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;IACtD,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAGD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;QACrB,QAAQ,EAAE,cAAc,CAAC;QACzB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1C,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;QACtD,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,QAAQ,EAAE,KAAK,CAAC;YACd,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC,CAAC;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,uEAAuE;QACvE,mBAAmB,CAAC,EAAE,0BAA0B,GAAG;YACjD,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;SACrD,CAAC;QACF,KAAK,CAAC,EAAE;YACN,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;YAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;YAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;YAChC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;SAClC,CAAC;KACH,CAAC;IACF,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,QAAQ,EAAE,cAAc,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC"}