From bc04ae93071ce5364341b2c797d69a8db3b00938 Mon Sep 17 00:00:00 2001 From: johndoe6345789 Date: Thu, 15 Jan 2026 01:53:59 +0000 Subject: [PATCH] chore: Add CONTRACT.md - Binding Software Design Specification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is a formal, legal-contractual design specification that defines all requirements for MetaBuilder, including: FUNCTIONAL REQUIREMENTS: - Data-driven architecture (URL → DB → JSON → Renderer) - Single unified DBAL client (no alternatives permitted) - Database access ONLY through DBAL (no direct Prisma) - All routes in database (not hardcoded) - All components as JSON (not hardcoded React) NON-FUNCTIONAL REQUIREMENTS: - npm run build MUST succeed - npm run typecheck MUST have zero errors - npm run dev MUST start - npm run test:e2e MUST run without errors - DBAL MUST compile to dist/ - Database MUST initialize successfully ARCHITECTURE REQUIREMENTS: - One DBAL implementation only (no duplicates) - Clear component boundaries - No dead/broken code - All dependencies declared and pinned - No undocumented features or hidden logic ACCEPTANCE CRITERIA: ALL of the above must be true before any feature work proceeds. CURRENT STATUS: ❌ NOT COMPLIANT - See CODEBASE_RECOVERY_PLAN.md for fix sequence This CONTRACT.md overrides all prior assumptions. It is binding. Co-Authored-By: Claude Haiku 4.5 --- CONTRACT.md | 463 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 463 insertions(+) create mode 100644 CONTRACT.md diff --git a/CONTRACT.md b/CONTRACT.md new file mode 100644 index 000000000..f20b8bace --- /dev/null +++ b/CONTRACT.md @@ -0,0 +1,463 @@ +# MetaBuilder Software Design Specification + +**Legal and Contractual Form** + +⸻ + +## 1. DEFINITIONS + +For purposes of this Design Specification (the "Specification"), the following terms shall have the meanings set forth below: + +**1.1 "Software Package"** means MetaBuilder, the complete collection of executable code, source code, configuration files, documentation, interfaces, and related materials described herein. + +**1.2 "System"** means the operational environment in which MetaBuilder is installed, executed, or accessed, including but not limited to development environments, test environments, and production deployment environments. + +**1.3 "Deliverables"** means all items required to be produced, transferred, or made available pursuant to this Specification, including source code, compiled artifacts, documentation, and test artifacts. + +**1.4 "Acceptance Criteria"** means the objective, measurable standards set forth herein by which conformity of MetaBuilder shall be evaluated. + +**1.5 "Defect"** means any failure of MetaBuilder to conform materially to this Specification. + +**1.6 "Specification Compliance"** means MetaBuilder demonstrates full conformity with all requirements enumerated in this Specification through verifiable, reproducible testing. + +⸻ + +## 2. PURPOSE AND SCOPE + +**2.1** The purpose of this Specification is to define, in precise and binding terms, the functional, non-functional, architectural, and operational requirements of MetaBuilder. + +**2.2** This Specification shall govern the design, development, implementation, testing, delivery, and maintenance of MetaBuilder. + +**2.3** Any functionality, behavior, or characteristic not expressly described herein shall be deemed out of scope, unless subsequently agreed in writing by all Parties. + +**2.4** This Specification constitutes a binding contract and supersedes all prior understandings, documentation, or assumptions regarding MetaBuilder's design and behavior. + +⸻ + +## 3. GENERAL DESIGN REQUIREMENTS + +**3.1** MetaBuilder shall be designed in accordance with commercially reasonable software engineering standards prevailing at the time of development, specifically: +- Deterministic execution (no race conditions, no uncontrolled state) +- Modular architecture with clear component boundaries +- Explicit over implicit configuration +- Documented behavior + +**3.2** MetaBuilder shall be modular, maintainable, and extensible without requiring material refactoring of existing components. + +**3.3** MetaBuilder shall not include: +- Undocumented features +- Hidden logic or side effects +- Intentionally obfuscated code +- Dead code or unused implementations +- Broken or non-functional code paths + +**3.4** All components shall operate deterministically under identical inputs and environmental conditions, except where nondeterminism is expressly specified in this Specification. + +**3.5** All code shall be buildable, compilable, and testable without errors or warnings that prevent successful compilation. + +**3.6** No component shall reference, depend upon, or require code that does not exist, cannot be compiled, or is marked as incomplete or experimental. + +⸻ + +## 4. FUNCTIONAL REQUIREMENTS + +**4.1 Core Data-Driven Architecture** + +MetaBuilder shall implement the following architectural pattern: +``` +Browser URL → Database Query → JSON Component → Generic Renderer → React → User +``` + +**4.1.1** Routes shall be stored in the `PageConfig` database table, not hardcoded in application code. + +**4.1.2** Components shall be defined as JSON definitions in packages, not imported directly as React components. + +**4.1.3** All database access shall flow through the DBAL (Database Abstraction Layer), not through direct Prisma calls or other adapters. + +**4.2 DBAL (Database Abstraction Layer) Requirements** + +MetaBuilder shall provide a single, unified DBAL client: + +**4.2.1** DBAL Exports: The DBAL package (`@metabuilder/dbal`) shall export: +- `getDBALClient()` - factory for creating DBALClient instances +- `useDBAL()` - alias for getDBALClient for React contexts +- `seedDatabase(db: DBALClient)` - seed orchestration function +- `getPrismaClient()` - access to underlying Prisma (if needed) +- All entity operation types (users, pageConfigs, sessions, packages, etc.) + +**4.2.2** DBAL Compilation: The TypeScript DBAL at `/dbal/development/` shall: +- Compile without errors or warnings +- Generate `types.generated.ts` successfully via codegen +- Output compiled code to `/dbal/development/dist/` +- Export all types and functions from `dist/index.js` + +**4.2.3** DBAL Entity Operations: The DBALClient shall provide type-safe operations for all entities: +- `db.users.list()`, `findOne()`, `create()`, `update()`, `delete()` +- `db.pageConfigs.list()`, `findOne()`, `create()`, `update()`, `delete()` +- `db.sessions.list()`, `findOne()`, `create()` +- `db.packages.list()`, `findOne()` +- All operations shall validate input against YAML schemas +- All operations shall enforce ACL (Access Control List) rules + +**4.2.4** DBAL shall be the sole authoritative database interface. No other database access patterns are permitted (no direct Prisma, no raw adapters, no custom queries). + +**4.3 Frontend Integration** + +**4.3.1** The Next.js frontend shall import DBAL from `@/dbal`: +```typescript +import { getDBALClient } from '@/dbal' +const db = getDBALClient() +``` + +**4.3.2** All database operations in the frontend shall use DBALClient entity methods, not: +- Direct Prisma calls +- Old `getAdapter()` function +- Custom adapter wrappers +- Database-dbal helper functions + +**4.3.3** The frontend shall have a single unified integration point at `/frontends/nextjs/src/lib/db-client.ts` that exports: +```typescript +export const db: DBALClient // Singleton instance +export function getDB(): DBALClient // Factory function +export type { DBALClient } +``` + +**4.3.4** All code in `/frontends/nextjs/src/lib/` that performs database operations shall import from `@/lib/db-client`, not from any other database integration. + +**4.4 Each Functional Capability shall**: +- Accept inputs strictly within defined parameters +- Produce outputs consistent with documented formats +- Fail gracefully upon invalid input or environmental fault +- Log failures with sufficient context for debugging + +**4.5 API Contract** + +**4.5.1** All programmatic interfaces shall be: +- Versioned (major.minor.patch) +- Documented with clear input/output specifications +- Backward-compatible within a major version +- Type-safe (TypeScript types provided) + +**4.6 User-Facing Functionality** + +**4.6.1** Behavior shall be consistent across all supported platforms and environments (development, test, production). + +**4.6.2** All user-facing operations shall complete within defined time limits. + +⸻ + +## 5. NON-FUNCTIONAL REQUIREMENTS + +**5.1 Buildability** + +MetaBuilder shall meet the following build requirements: + +**5.1.1** The command `npm run build` shall complete successfully without errors or warnings. + +**5.1.2** The command `npm run typecheck` shall complete with zero type errors. + +**5.1.3** The command `npm run lint` shall report zero critical violations. + +**5.1.4** Intermediate build steps shall be reproducible: +- `npm --prefix dbal/development run build` shall succeed +- `npm run db:generate` shall succeed +- `npm run db:push` shall succeed + +**5.2 Runtime Operations** + +**5.2.1** The command `npm run dev` shall start the development server without errors. + +**5.2.2** The command `npm run test:e2e` shall execute without database connection errors or import failures. + +**5.2.3** All operational commands shall be documented in the root `package.json` scripts section. + +**5.3 Database** + +**5.3.1** The database schema shall be defined in a single authoritative location: `/prisma/schema.prisma`. + +**5.3.2** When `npm run db:push` is executed, a valid SQLite database file shall be created at `/prisma/dev.db`. + +**5.3.3** The database schema shall be generated from YAML source files in `/dbal/shared/api/schema/entities/` using automated code generation. + +**5.3.4** All database operations shall enforce multi-tenant isolation by filtering on `tenantId`. + +**5.4 Performance** + +MetaBuilder shall meet the following performance characteristics: + +**5.4.1** Response times shall be within defined thresholds under nominal load (to be specified in operational documentation). + +**5.4.2** Degradation under stress shall be predictable (no uncontrolled resource exhaustion). + +**5.4.3** No operation shall cause infinite loops, memory leaks, or hung processes under normal usage. + +**5.5 Reliability** + +MetaBuilder shall: + +**5.5.1** Recover automatically from non-fatal errors where feasible. + +**5.5.2** Log failures in a reproducible and auditable manner. + +**5.5.3** Not have single points of failure, or explicitly document where they exist. + +**5.5.4** Handle edge cases gracefully (empty results, missing records, permission denial). + +**5.6 Security** + +MetaBuilder shall: + +**5.6.1** Enforce authentication and authorization controls where applicable. + +**5.6.2** Protect data in transit and at rest using industry-standard mechanisms. + +**5.6.3** Not intentionally expose vulnerabilities, backdoors, or insecure defaults. + +**5.6.4** Validate all user inputs before processing. + +**5.6.5** Enforce ACL rules at the DBAL layer for all entity operations. + +⸻ + +## 6. ARCHITECTURE AND DESIGN CONSTRAINTS + +**6.1** MetaBuilder shall be structured into discrete components with clearly defined responsibilities: +- DBAL layer (`/dbal/development/`) +- Frontend layer (`/frontends/nextjs/`) +- Package system (`/packages/`) +- Seed data (`/seed/`) + +**6.2** Inter-component communication shall occur only through documented interfaces. + +**6.3** MetaBuilder shall not depend upon proprietary or third-party components except those expressly identified and approved in `package.json`. + +**6.4** All dependencies shall be: +- Declared in `package.json` +- Version-pinned (not floating versions) +- Reproducible across environments +- Documented in technical documentation + +**6.5** There shall be one and only one DBAL client implementation. No duplicate, alternative, or experimental implementations are permitted in the codebase. + +**6.6** Code Consolidation: The following shall be eliminated or consolidated: +- `/frontends/nextjs/src/lib/dbal-client/` - old adapter wrapper (DELETE) +- `/frontends/nextjs/src/lib/database-dbal/` - alternative wrapper (DELETE) +- `/frontends/nextjs/src/lib/dbal/` - stub implementations (DELETE or complete) +- `/frontends/nextjs/src/lib/db/core/dbal-client/` - integration stubs (DELETE) +- All imports of `getAdapter()` from old locations (REPLACE with `@/dbal` imports) +- All imports of `prisma` from `@/lib/config/prisma` (REPLACE with `@/dbal`) + +**6.7** Path Resolution: TypeScript path aliases shall resolve correctly: +- `@/dbal` → `../../node_modules/@metabuilder/dbal` (npm package) +- `@/*` → `./src/*` (local files) +- No circular references or ambiguous paths + +⸻ + +## 7. DATA MANAGEMENT + +**7.1** MetaBuilder shall process data solely for its intended operational purpose. + +**7.2** Data storage formats shall be: +- Documented and stable across minor revisions +- Compliant with the Prisma schema +- Validated against YAML entity schemas + +**7.3** MetaBuilder shall not: +- Delete, alter, or transmit data except as explicitly required for correct operation +- Store data outside the primary database +- Expose database credentials in logs or error messages + +**7.4** Database Schema Authority: The single source of truth for database schema is `/dbal/shared/api/schema/entities/` (YAML files). The Prisma schema at `/prisma/schema.prisma` shall be auto-generated from YAML. + +**7.5** Seed Data: The single source of truth for seed data is `/seed/` (YAML and JSON files). Seed data shall never be hardcoded in application code. + +⸻ + +## 8. TESTING AND VERIFICATION + +**8.1** MetaBuilder shall be subject to automated and manual testing sufficient to demonstrate compliance with this Specification. + +**8.2** Test Coverage Requirements: + +**8.2.1** Unit Testing: +- Core logic shall have unit test coverage +- Framework: Vitest +- Command: `npm run test:unit` +- Result: All tests shall pass + +**8.2.2** Integration Testing: +- Component boundaries shall be tested +- Database operations shall be tested +- Package system shall be tested +- Included in E2E test suite + +**8.2.3** End-to-End Testing: +- Real browser automation using Playwright +- All major workflows shall have E2E coverage +- Command: `npm run test:e2e` +- Result: All tests shall pass without errors + +**8.2.4** Type Checking: +- TypeScript compiler shall report zero errors +- Command: `npm run typecheck` +- Result: Zero type errors + +**8.3** Acceptance Testing: The following acceptance criteria must pass: + +**8.3.1 Build Acceptance**: +```bash +npm run build # Must succeed +npm run typecheck # Must have zero errors +npm run lint # Must have zero critical errors +``` + +**8.3.2 Runtime Acceptance**: +```bash +npm run dev # Must start without errors +npm run test:e2e # Must complete without errors +npm run test:unit # Must pass all tests +``` + +**8.3.3 Database Acceptance**: +```bash +npm run db:generate # Must succeed +npm run db:push # Must create database +ls /prisma/dev.db # Must exist +``` + +**8.3.4 DBAL Acceptance**: +```bash +npm --prefix dbal/development run build # Must succeed +ls /dbal/development/dist/index.js # Must exist +npm --prefix dbal/development run test # Must pass +``` + +**8.4** Test artifacts shall be retained and made available upon reasonable request. + +⸻ + +## 9. DELIVERY AND DOCUMENTATION + +**9.1** Deliverables shall include: + +**9.1.1** Source Code: +- All source code in `/dbal/`, `/frontends/`, `/packages/`, `/seed/` +- Build configuration files +- Test files and test data + +**9.1.2** Build Artifacts: +- Compiled DBAL at `/dbal/development/dist/` +- Node modules and dependencies +- Database schema + +**9.1.3** Documentation: +- This CONTRACT.md (design specification) +- README.md (project overview) +- CLAUDE.md (development instructions) +- AGENTS.md (AI assistant guidelines) +- ARCHITECTURE.md (system design) +- CODEBASE_RECOVERY_PLAN.md (recovery steps) +- API documentation (OpenAPI/Swagger - in progress) + +**9.2** Documentation Requirements: + +**9.2.1** Documentation shall be: +- Accurate and current +- Consistent with the delivered code +- Sufficient for competent operation and maintenance +- Updated whenever code behavior changes + +**9.2.2** Documentation shall include: +- Architecture diagrams +- API specifications +- Configuration options +- Operational procedures +- Troubleshooting guides + +**9.3** Codebase State: The codebase shall be in a documented, known state: +- No broken imports +- No dead code +- No experimental branches mixed with stable code +- All code either functional or explicitly marked as "WIP" with recovery plan + +⸻ + +## 10. ACCEPTANCE CRITERIA + +**10.1** MetaBuilder shall be deemed Accepted only upon demonstrable compliance with all Acceptance Criteria enumerated in Section 8.3. + +**10.2** Failure to meet any material requirement of this Specification shall constitute grounds for rejection. + +**10.3** The codebase must achieve the following state before any feature work or refactoring can proceed: + +``` +REQUIRED STATE: +✅ npm run build succeeds +✅ npm run typecheck returns zero errors +✅ npm run dev starts without errors +✅ npm run test:e2e runs without import/DB errors +✅ npm run test:unit passes all tests +✅ DBAL compiles to dist/ successfully +✅ Database can be initialized and seeded +✅ All DBAL exports accessible from @/dbal +✅ Zero references to old getAdapter() pattern +✅ Zero dead/broken code in codebase +``` + +**10.4** Current Status Assessment: + +As of January 15, 2026: +- ❌ npm run build - FAILS +- ❌ npm run typecheck - FAILS (27 errors) +- ❌ npm run dev - FAILS +- ❌ npm run test:e2e - FAILS +- ❌ DBAL build - FAILS (16+ errors) +- ❌ Database - NOT INITIALIZED +- ❌ ACCEPTANCE CRITERIA - NOT MET + +**10.5** Recovery Plan: See `CODEBASE_RECOVERY_PLAN.md` for detailed steps to achieve Acceptance. + +⸻ + +## 11. CHANGE CONTROL + +**11.1** No modification to this Specification shall be valid unless made in writing and executed by authorized representatives of all Parties. + +**11.2** Any approved change shall be incorporated into a revised version of this CONTRACT.md with updated date and version number. + +**11.3** Changes shall be tracked in git commit history with clear reference to the change request. + +⸻ + +## 12. GOVERNING INTERPRETATION + +**12.1** In the event of ambiguity or conflict, this Specification shall be interpreted to favor: +- **Determinism over flexibility** - predictable behavior +- **Explicit requirements over implied behavior** - no assumptions +- **Written terms over inferred intent** - what is stated, not what is assumed +- **Functional code over theoretical architecture** - code that runs matters more than perfect design +- **Measurable criteria over subjective assessment** - pass/fail tests, not "probably works" + +**12.2** All decisions regarding MetaBuilder's direction shall be made in accordance with this Specification. + +**12.3** If existing code violates this Specification, the Specification takes precedence, and the code must be corrected. + +⸻ + +## 13. EFFECTIVE DATE AND SIGNATURES + +**Effective Date:** January 15, 2026 + +**Status:** MetaBuilder does NOT currently comply with this Specification. + +**Next Actions:** +1. Execute CODEBASE_RECOVERY_PLAN.md to achieve compliance +2. Verify all Acceptance Criteria in Section 8.3 and 10.3 +3. Upon compliance, this Specification becomes the binding standard for all future development + +⸻ + +**ACKNOWLEDGMENT**: By proceeding with development and deployment of MetaBuilder, all parties agree to comply with this Design Specification as if it were a binding legal contract. + +No code shall be committed, deployed, or considered "complete" unless it meets all requirements enumerated herein.