Audit HUMMBL Model References

Instructions

Implementation Reference

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

  The core audit logic that validates model codes against HUMMBL Base120: checks for existence (NotFound), transformation alignment (WrongTransformation), and duplicates (Duplicate). Returns a MethodologyAuditResult.

  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/tools/methodology.ts:69-103 (schema)

  MCP tool registration for 'audit_model_references' with inputSchema (array of {code, expectedTransformation}) and outputSchema (methodologyId, counts, issues).

  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(),
          })
        ),
      }),

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

  Helper function findTransformationKeyForModel that scans all transformations to find which one owns a given model code, used during transformation alignment checking.

  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,
    });
  }

• src/types/domain.ts:72-229 (helper)

  Type definitions supporting the audit: DialecticalMethodology, ModelReferenceIssue, ModelReferenceIssueType, MethodologyAuditResult, and AuditInputItem interface.

  export interface DialecticalMethodology {
    id: string;
    title: string;
    version: string;
    summary: string;
    documentUrl?: string;
    totalPages?: number;
    modelsReferenced: string[];
    stages: StageModelMapping[];
    metaModels: string[];
  }
  
  export type ModelReferenceIssueType = "NotFound" | "WrongTransformation" | "Duplicate" | "Unknown";
  
  export interface ModelReferenceIssue {
    code: string;
    issueType: ModelReferenceIssueType;
    message: string;
    expectedTransformation?: TransformationType;
    actualTransformation?: TransformationType;
  }
  
  export interface MethodologyAuditResult {
    methodologyId: string;
    documentVersion: string;
    totalReferences: number;
    validCount: number;
    invalidCount: number;
    issues: ModelReferenceIssue[];
  }
  
  /**
   * Domain-wide error type for HUMMBL Base120 operations.
   */
  export type DomainError =
    | { type: "NotFound"; entity: string; code?: string }
    | { type: "ValidationError"; field?: string; message: string }
    | { type: "Conflict"; entity: string; message: string }
    | { type: "Internal"; message: string }
    | { type: "Unknown"; message: string };
  
  /**
   * Result type for type-safe error handling (Railway-Oriented Programming).
   * Uses an `ok` discriminant to align with HUMMBL global patterns.
   */
  export type Result<T, E = DomainError> = { ok: true; value: T } | { ok: false; error: E };
  
  export const ok = <T>(value: T): Result<T, never> => ({
    ok: true,
    value,
  });
  
  export const err = <E>(error: E): Result<never, E> => ({
    ok: false,
    error,
  });
  
  /**
   * Type guard for Result success case.
   */
  export function isOk<T, E>(result: Result<T, E>): result is { ok: true; value: T } {
    return result.ok === true;
  }
  
  /**
   * Type guard for Result error case.
   */
  export function isErr<T, E>(result: Result<T, E>): result is { ok: false; error: E } {
    return result.ok === false;
  }
  
  export function isNotFoundError(
    error: DomainError
  ): error is Extract<DomainError, { type: "NotFound" }> {
    return error.type === "NotFound";
  }
  
  /**
   * API Key tiers with rate limits and permissions
   */
  export type ApiKeyTier = "free" | "pro" | "enterprise";
  
  export interface ApiKeyInfo {
    id: string;
    key: string;
    tier: ApiKeyTier;
    name: string;
    createdAt: string;
    lastUsed?: string;
    usageCount: number;
    rateLimit: {
      requestsPerHour: number;
      requestsPerDay: number;
    };
    permissions: readonly string[];
    isActive: boolean;
  }
  
  /**
   * Authentication result types
   */
  export type AuthResult = Result<ApiKeyInfo, AuthError>;
  
  export type AuthError =
    | { type: "MISSING_AUTH"; message: string }
    | { type: "INVALID_FORMAT"; message: string }
    | { type: "KEY_NOT_FOUND"; message: string }
    | { type: "KEY_INACTIVE"; message: string }
    | { type: "RATE_LIMIT_EXCEEDED"; message: string }
    | { type: "INTERNAL_ERROR"; message: string };
  
  /**
   * Workflow types for guided multi-turn problem solving
   */
  
  export type WorkflowType = "root_cause_analysis" | "strategy_design" | "decision_making";
  
  export interface WorkflowStep {
    stepNumber: number;
    transformation: TransformationType;
    models: string[]; // Model codes to apply
    guidance: string; // What to do in this step
    questions: string[]; // Prompts to guide thinking
    expectedOutput: string; // What should result from this step
  }
  
  export interface WorkflowTemplate {
    name: WorkflowType;
    displayName: string;
    description: string;
    problemTypes: string[]; // When to use this workflow
    steps: WorkflowStep[];
    estimatedDuration: string; // e.g., "15-30 minutes"
  }
  
  export interface WorkflowState {
    workflowName: WorkflowType;
    currentStep: number;
    totalSteps: number;
    startedAt: string;
    lastUpdatedAt: string;
    completed: boolean;
    stepResults: Record<number, string>; // User's insights from each step
  }
  
  export interface WorkflowProgress {
    workflow: WorkflowType;
    displayName: string;
    currentStep: number;
    totalSteps: number;
    transformation: TransformationType;
    guidance: string;
    suggestedModels: string[];
    questions: string[];
    nextAction: string;
    canResume: boolean;
  }

• src/server.ts:19-27 (registration)

  Server initialization that calls registerMethodologyTools(server) to register the audit_model_references tool on the MCP server.

  export function createServer(): McpServer {
    const server = new McpServer({
      name: "hummbl-mcp-server",
      version: SERVER_VERSION,
    });
  
    // Register all tools
    registerModelTools(server);
    registerMethodologyTools(server);