metabuilder/docs/CONTRACT.md

METABUILDER SOFTWARE DESIGN SPECIFICATION

A Contractual and Binding Design Specification

This document defines the non-negotiable design, quality, and operational requirements for the MetaBuilder codebase. All code contributions are subject to these requirements. Non-compliance is grounds for immediate rejection, reversal, and remediation.

---

PREAMBLE

Status: ACTIVE AND BINDING Date: January 15, 2026 Scope: All commits to the MetaBuilder repository

The MetaBuilder codebase MUST maintain operational integrity, type safety, testability, and architectural correctness. These requirements are not aspirational—they are contractual obligations.

Key Principle: Code must be proven compliant before acceptance. Presumption is against acceptance until demonstrated otherwise.

---

ARTICLE I: CORE REQUIREMENTS

REQUIREMENT 1: BUILD COMPLIANCE

Specification:

• npm run build MUST complete without errors or warnings that prevent compilation
• Build artifacts MUST be generated to their expected output directories
• Build process MUST be deterministic (identical inputs produce identical outputs across runs)

Verification:

npm run build && echo "PASS" || echo "FAIL"

Remediation on Failure:

• Immediate rejection of commit
• Automatic revert if merged without approval
• Responsible engineer must correct and resubmit

Current Status: ❌ FAILED — Frontend build fails. Correction mandatory.

---

REQUIREMENT 2: TYPE SAFETY

Specification:

• npm run typecheck MUST complete with zero TypeScript errors
• Strict mode flags MUST remain enabled (exactOptionalPropertyTypes: true)
• Use of @ts-ignore and @ts-expect-error is prohibited except with explicit justification approved by code review
• All implicit any types MUST be resolved to concrete types

Verification:

npm run typecheck && [ $(npm run typecheck 2>&1 | grep -c "error") -eq 0 ] && echo "PASS" || echo "FAIL"

Remediation on Failure:

• Immediate rejection of commit
• Type violations MUST be fixed, not suppressed
• Code must be corrected to comply with type system, not weakened

Current Status: ❌ FAILED — 27 TypeScript errors. Correction mandatory.

---

REQUIREMENT 3: IMPORT RESOLUTION

Specification:

• All import statements MUST reference modules that exist
• No broken module references are permitted
• Path aliases (@/dbal, etc.) MUST resolve to existing files or npm packages
• No circular dependencies are permitted

Verification:

npm run typecheck  # catches unresolved imports

Remediation on Failure:

• Immediate rejection of commit
• All missing modules MUST be created or import statements MUST be corrected
• Code cannot reference non-existent files

Current Status: ❌ FAILED — 27 broken imports in frontend. Correction mandatory.

---

REQUIREMENT 4: DATABASE INITIALIZATION

Specification:

• Database schema MUST be initialized successfully
• npm run db:push MUST complete without errors
• Database file MUST exist and contain initialized schema
• Database operations MUST be idempotent (safe to run multiple times)

Verification:

npm run db:generate
npm run db:push
test -f /dbal/development/prisma/dev.db && echo "PASS" || echo "FAIL"

Remediation on Failure:

• Schema inconsistencies MUST be resolved
• Migration scripts MUST be corrected
• Tests cannot proceed until database initializes

Current Status: ❌ FAILED — Database not initialized. Correction mandatory.

---

REQUIREMENT 5: DBAL COMPILATION

Specification:

• DBAL TypeScript source MUST compile without errors
• npm --prefix dbal/development run build MUST succeed
• Compiled output MUST exist in /dbal/development/dist/
• All required exports MUST be present in compiled output
• Generated type files MUST be created and included in dist

Verification:

npm --prefix dbal/development run build
test -f dbal/development/dist/index.js && echo "PASS" || echo "FAIL"

Remediation on Failure:

• All TypeScript errors in DBAL MUST be resolved
• Missing code generation scripts MUST be created
• Codegen tools MUST produce required artifacts

Current Status: ❌ FAILED — DBAL has 16+ errors. Correction mandatory.

---

REQUIREMENT 6: DOCUMENTATION

Specification:

• Every commit message MUST explain:
  • WHAT changed (specific files/functions modified)
  • WHY it changed (business/technical rationale)
  • HOW to verify it works (test commands or validation steps)
• Code MUST be self-documenting (clear variable/function names)
• Complex logic MUST have explanatory comments describing the why, not the what
• All public APIs MUST have JSDoc/TSDoc comments

Remediation on Failure:

• Commit rejected for inadequate documentation
• Author MUST provide complete explanation before acceptance

Current Status: ⚠️ INCOMPLETE — Existing code lacks documentation. Future commits must comply.

---

REQUIREMENT 7: NO DEAD CODE

Specification:

• All committed code MUST be active and executed during normal operation
• Unused functions, variables, or modules MUST NOT be committed
• Stub files or incomplete implementations MUST be explicitly marked as work-in-progress with clear status
• All TODO comments MUST reference a tracking issue and expected completion date

Remediation on Failure:

• Code rejected if unused or incomplete
• Dead code MUST be deleted or completed

Current Status: ❌ FAILED — 39 DBAL stub files committed but non-functional. Correction mandatory.

---

REQUIREMENT 8: ARCHITECTURAL COMPLIANCE

Specification:

• Architecture MUST match the specification defined in ARCHITECTURE.md
• DBAL MUST be self-contained and independently deployable
• Seed data and Prisma schema MUST reside in DBAL, not at root level
• Multiple conflicting implementations are prohibited
• Database logic MUST not be scattered across the codebase

Remediation on Failure:

• Code rejected if architecture violations exist
• Refactoring MUST be completed before acceptance
• Architecture must be corrected before code cleanup

Current Status: ❌ FAILED — Seed at root, schema at root, multiple DBAL implementations. Correction mandatory.

---

ARTICLE II: VERIFICATION PROTOCOL

All commits are subject to the following verification sequence (in order):

Verification Checklist

• BUILD CHECK — npm run build succeeds (REQUIREMENT 1)
• TYPE CHECK — npm run typecheck returns 0 errors (REQUIREMENT 2)
• IMPORT CHECK — All imports resolve correctly (REQUIREMENT 3)
• DATABASE CHECK — npm run db:push succeeds (REQUIREMENT 4)
• DBAL CHECK — DBAL compiles to dist/ (REQUIREMENT 5)
• DOCUMENTATION CHECK — Commit message and code comments complete (REQUIREMENT 6)
• CODE CHECK — No dead code or stubs (REQUIREMENT 7)
• ARCHITECTURE CHECK — Complies with ARCHITECTURE.md (REQUIREMENT 8)
• TEST CHECK — npm run test:e2e and npm run test:unit pass

Standard: ALL checks must pass. If ANY check fails, the commit is rejected.

---

ARTICLE III: CURRENT COMPLIANCE STATUS

Evaluation Date: January 15, 2026

Compliance Report

Requirement	Status	Details
1. Build Compliance	❌ FAIL	npm run build fails
2. Type Safety	❌ FAIL	27 TypeScript errors
3. Import Resolution	❌ FAIL	27 broken imports in frontend
4. Database Init	❌ FAIL	No .db file created
5. DBAL Compilation	❌ FAIL	16+ compilation errors, missing codegen
6. Documentation	⚠️ WARN	Insufficient for complex code
7. No Dead Code	❌ FAIL	39 stub files, 20+ obsolete wrappers
8. Architecture	❌ FAIL	Seed/schema at root, multiple DBAL impls

Overall Status

🚨 NON-COMPLIANT

The codebase fails to meet 7 out of 8 core requirements. Feature development is suspended until core requirements are satisfied.

---

ARTICLE IV: REMEDIATION PATHWAY

Phase 0: Architecture Restructure (FIRST)

Execute ARCHITECTURE_RESTRUCTURE.md:

1. Move /seed/ → /dbal/shared/seeds/
2. Move /prisma/ → /dbal/development/prisma/
3. Update package.json scripts
4. Update DBAL exports
5. Delete old folders
6. Verify no broken references

Timeline: 30-60 minutes Mandatory before Phase 1

Phase 1: DBAL Compilation Recovery

Execute CODEBASE_RECOVERY_PLAN.md:

1. Fix/create codegen script (gen_types.ts)
2. Fix 8 TypeScript strict mode violations
3. Compile DBAL to dist/
4. Verify all exports available

Timeline: 2-3 hours Mandatory before Phase 2

Phase 2: Database Initialization

1. Generate Prisma client: npm run db:generate
2. Initialize database: npm run db:push
3. Verify: /dbal/development/prisma/dev.db exists

Timeline: 30 minutes

Phase 3: Frontend Recovery

1. Remove DBAL source from frontend tsconfig
2. Fix Next.js route handler signatures (4 routes)
3. Verify typecheck: 27 errors → 0 errors
4. Verify build: succeeds

Timeline: 1-2 hours

Phase 4: Verification

Run full test suite:

• npm run build → ✅ PASS
• npm run typecheck → ✅ 0 ERRORS
• npm run test:unit → ✅ ALL PASS
• npm run test:e2e → ✅ ALL RUN
• npm run dev → ✅ STARTS

Timeline: 30 minutes

Total Estimated Effort: 4-5 hours to full compliance

---

ARTICLE V: ENFORCEMENT

Enforcement Mechanism

A pre-commit hook MUST enforce these requirements before code is committed:

#!/bin/bash

echo "ENFORCEMENT: Verifying code compliance..."

# Requirement 1: Build Compliance
npm run build || { echo "FAIL: Build does not compile"; exit 1; }

# Requirement 2: Type Safety
npm run typecheck || { echo "FAIL: TypeScript errors exist"; exit 1; }

# Requirement 3: Import Resolution (caught by typecheck)
# Already checked above

# Requirement 7: No dead code (lint)
npm run lint || { echo "FAIL: Lint errors detected"; exit 1; }

# All checks passed
echo "PASS: Code is compliant. Commit allowed."
exit 0

This hook is NOT negotiable.

---

ARTICLE VI: STANDARDS GOING FORWARD

Post-Recovery Standards

Once the codebase achieves compliance, all future commits MUST:

1. Pass all verification checks (ARTICLE II)
2. Include complete documentation (commit message + code comments)
3. Have zero type errors (strict mode enabled)
4. Have zero broken imports (all modules exist)
5. Maintain database consistency (schema + seed aligned)
6. Comply with architecture (no duplicate implementations)
7. Be testable (include or update tests)
8. Be reviewable (understandable in 5 minutes by another engineer)

Probation Period

After achieving initial compliance, the codebase enters a probation period:

• Duration: 30 consecutive commits with zero violations
• Requirement: All commits must pass all verification checks
• Violation: Any failed check results in immediate revert
• Post-Probation: Full feature development can resume

---

ARTICLE VII: BINDING AUTHORITY

This specification IS binding.

This is not guidance. This is not aspirational. This is contractual requirement.

• All developers agree to these terms by committing code
• All code reviewers agree to enforce these terms
• All merged code is warrantied to meet these requirements

Failure to comply is grounds for:

• Immediate rejection of commit
• Automatic reversion if merged
• Loss of merge privileges until pattern changes
• Code review assignment until compliant pattern demonstrated

---

ARTICLE VIII: CHANGE CONTROL

Any modification to this specification requires:

1. Written proposal with justification
2. Approval by all active maintainers
3. Update to this file with dated change record
4. Communication to all contributors

No unilateral changes permitted.

---

SIGNATURES & ACKNOWLEDGMENT

By committing code to MetaBuilder, you acknowledge and agree to:

• ✅ I have read this specification completely
• ✅ I understand these are contractual requirements, not suggestions
• ✅ I agree to comply with all verification checks before committing
• ✅ I agree to maintain these standards in all future contributions
• ✅ I understand non-compliance results in automatic rejection/revert
• ✅ I understand this is binding for all code I contribute

---

APPENDIX A: QUICK REFERENCE

Check Before Every Commit

# 1. Build
npm run build

# 2. Types
npm run typecheck

# 3. Tests
npm run test:unit
npm run test:e2e

# 4. Lint
npm run lint

# If all pass, commit is allowed

Execution Commands

# Architecture Restructure
# Execute: ARCHITECTURE_RESTRUCTURE.md (30-60 min)

# DBAL Recovery
# Execute: CODEBASE_RECOVERY_PLAN.md (4-5 hours)

# Database Setup
npm run db:generate
npm run db:push

# Verification
npm run dev  # Should start without errors

---

APPENDIX B: DEFINITIONS

• Build: The process of compiling TypeScript to JavaScript and generating artifacts
• Compliance: Meeting all requirements defined in Articles I-VIII
• Non-Compliance: Failing to meet any core requirement
• Code Review: Process of verifying compliance before merge
• Acceptance Criteria: Objective, measurable standards for each requirement
• Remediation: Actions required to bring non-compliant code into compliance
• Probation: Period of heightened monitoring following initial compliance achievement

---

Document Status: ACTIVE Last Updated: January 15, 2026 Version: 1.0 Authority: Project Specification Binding: YES

This specification supersedes all prior informal quality guidelines and represents the authoritative standard for MetaBuilder code quality.