audit_model_references

Validate HUMMBL model references for existence, transformation alignment, and duplicate detection to ensure data integrity.

Instructions

Audit a list of HUMMBL model references for existence, transformation alignment, and duplicates.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`items`	Yes

Implementation Reference

src/tools/methodology.ts:68-143 (registration)

Full registration of the MCP 'audit_model_references' tool, including description, Zod input/output schemas, and the inline async handler function that processes the request and calls the core audit logic.

// Tool: Audit model references against HUMMBL Base120 and methodology expectations
server.registerTool(
  "audit_model_references",
  {
    title: "Audit HUMMBL Model References",
    description:
      "Audit a list of HUMMBL model references for existence, transformation alignment, and duplicates.",
    inputSchema: z.object({
      items: z
        .array(
          z.object({
            code: z.string().min(2).describe("Model code, e.g., IN11, CO4"),
            expectedTransformation: z
              .enum(["P", "IN", "CO", "DE", "RE", "SY"])
              .optional()
              .describe("Optional expected transformation key for this reference"),
          })
        )
        .min(1),
    }),
    outputSchema: z.object({
      methodologyId: z.string(),
      documentVersion: z.string(),
      totalReferences: z.number(),
      validCount: z.number(),
      invalidCount: z.number(),
      issues: z.array(
        z.object({
          code: z.string(),
          issueType: z.enum(["NotFound", "WrongTransformation", "Duplicate", "Unknown"]),
          message: z.string(),
          expectedTransformation: z.string().optional(),
          actualTransformation: z.string().optional(),
        })
      ),
    }),
  },
  async ({ items }) => {
    const auditItems: AuditInputItem[] = items.map((item) => ({
      code: item.code,
      expectedTransformation: item.expectedTransformation,
    }));

    const result = auditModelCodes(auditItems);

    if (!isOk(result)) {
      const error = result.error;
      const baseMessage =
        error.type === "ValidationError"
          ? error.message
          : `Unable to audit model references: ${error.type}`;

      return {
        content: [
          {
            type: "text" as const,
            text: baseMessage,
          },
        ],
        isError: true as const,
      };
    }

    const payload = result.value;

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(payload, null, 2),
        },
      ],
      structuredContent: payload as unknown as { [key: string]: unknown },
    };
  }
);

src/framework/self_dialectical.ts:91-170 (handler)

Core handler logic for auditing model references: normalizes codes, checks existence and transformation type using Base120 data, detects duplicates, computes statistics and issues list.

export function auditModelCodes(
  items: AuditInputItem[]
): Result<MethodologyAuditResult, DomainError> {
  if (items.length === 0) {
    return err({
      type: "ValidationError",
      field: "codes",
      message: "At least one model code must be provided for audit.",
    });
  }

  const normalizedItems = items.map((item) => ({
    code: item.code.toUpperCase(),
    expectedTransformation: item.expectedTransformation,
  }));

  const issues: ModelReferenceIssue[] = [];
  let validCount = 0;

  const seen = new Map<string, number>();

  for (const item of normalizedItems) {
    const currentCount = seen.get(item.code) ?? 0;
    seen.set(item.code, currentCount + 1);
  }

  for (const item of normalizedItems) {
    const modelResult = getModelByCode(item.code);

    if (!modelResult.ok) {
      issues.push({
        code: item.code,
        issueType: "NotFound",
        message: `Model code '${item.code}' was not found in HUMMBL Base120.`,
      });
      continue;
    }

    validCount += 1;

    const model = modelResult.value;

    const owningTransformationKey = findTransformationKeyForModel(model.code);

    if (item.expectedTransformation && owningTransformationKey) {
      if (owningTransformationKey !== item.expectedTransformation) {
        issues.push({
          code: item.code,
          issueType: "WrongTransformation",
          message: `Model '${item.code}' belongs to transformation '${owningTransformationKey}', not '${item.expectedTransformation}'.`,
          expectedTransformation: item.expectedTransformation,
          actualTransformation: owningTransformationKey,
        });
      }
    }

    const count = seen.get(item.code) ?? 0;
    if (count > 1) {
      issues.push({
        code: item.code,
        issueType: "Duplicate",
        message: `Model code '${item.code}' appears ${count} times in the provided references.`,
      });
    }
  }

  const totalReferences = normalizedItems.length;
  const invalidCount = issues.length;

  const result: MethodologyAuditResult = {
    methodologyId: METHODOLOGY_ID,
    documentVersion: METHODOLOGY_VERSION,
    totalReferences,
    validCount,
    invalidCount,
    issues,
  };

  return ok(result);
}

src/framework/self_dialectical.ts:86-89 (schema)
Type definition for audit input items, used in tool input schema and handler mapping.
```
export interface AuditInputItem {
  code: string;
  expectedTransformation?: TransformationType;
}
```

src/framework/self_dialectical.ts:172-201 (helper)

Helper functions to find the owning transformation key for a model code by scanning Base120 transformations.

function findTransformationKeyForModel(code: string): TransformationType | undefined {
  const transformationResult = getTransformationByKeyForModel(code);
  if (!transformationResult.ok) {
    return undefined;
  }
  return transformationResult.value;
}

function getTransformationByKeyForModel(code: string): Result<TransformationType, DomainError> {
  // We scan transformations to find which one owns this model.
  // Using base120 helpers keeps all logic in the framework layer.
  const possibleKeys: TransformationType[] = ["P", "IN", "CO", "DE", "RE", "SY"];

  for (const key of possibleKeys) {
    const transResult = getTransformationByKey(key);
    if (!transResult.ok) {
      continue;
    }
    const transformation = transResult.value;
    if (transformation.models.some((m) => m.code === code)) {
      return ok(key);
    }
  }

  return err({
    type: "NotFound",
    entity: "Transformation",
    code,
  });
}

HUMMBL MCP Server