micro-contracts 0.9.0

package/docs/guardrails-concept.svg

@@ -0,0 +1,252 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 1195" font-family="'Segoe UI', 'Helvetica Neue', Arial, sans-serif">
+  <defs>
+    <!-- Gradients -->
+    <linearGradient id="headerGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#1e3a5f"/>
+      <stop offset="100%" style="stop-color:#2d5a87"/>
+    </linearGradient>
+    <linearGradient id="specLaneGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#dbeafe"/>
+      <stop offset="100%" style="stop-color:#eff6ff"/>
+    </linearGradient>
+    <linearGradient id="implLaneGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#fee2e2"/>
+      <stop offset="100%" style="stop-color:#fef2f2"/>
+    </linearGradient>
+    <linearGradient id="generatorGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#a855f7"/>
+      <stop offset="100%" style="stop-color:#7c3aed"/>
+    </linearGradient>
+    <linearGradient id="mergeGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#22c55e"/>
+      <stop offset="100%" style="stop-color:#16a34a"/>
+    </linearGradient>
+    <linearGradient id="taskGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#67e8f9"/>
+      <stop offset="100%" style="stop-color:#22d3ee"/>
+    </linearGradient>
+    
+    <!-- Drop shadow filter -->
+    <filter id="shadow" x="-5%" y="-5%" width="110%" height="110%">
+      <feDropShadow dx="2" dy="3" stdDeviation="3" flood-opacity="0.15"/>
+    </filter>
+    <filter id="shadowSmall" x="-5%" y="-5%" width="110%" height="110%">
+      <feDropShadow dx="1" dy="2" stdDeviation="2" flood-opacity="0.1"/>
+    </filter>
+    
+    <!-- Arrow markers -->
+    <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#64748b"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1100" height="1195" fill="#f8fafc"/>
+  
+  <!-- Header -->
+  <rect x="20" y="15" width="1060" height="70" rx="8" fill="url(#headerGrad)" filter="url(#shadow)"/>
+  <text x="550" y="45" text-anchor="middle" fill="white" font-size="22" font-weight="600">AI-Driven Development Guardrails</text>
+  <text x="550" y="68" text-anchor="middle" fill="#94a3b8" font-size="13">Contract-first quality gates for TypeScript API development</text>
+
+  <!-- Two-Lane Headers -->
+  <rect x="20" y="100" width="530" height="35" rx="6" fill="#3b82f6"/>
+  <text x="285" y="123" text-anchor="middle" fill="white" font-size="14" font-weight="600">Spec Level (Contract Verification)</text>
+  
+  <rect x="550" y="100" width="530" height="35" rx="6" fill="#ef4444"/>
+  <text x="815" y="123" text-anchor="middle" fill="white" font-size="14" font-weight="600">Implementation Level (Code Verification)</text>
+
+  <!-- Lane backgrounds -->
+  <rect x="20" y="135" width="530" height="770" rx="0 0 8 8" fill="url(#specLaneGrad)" stroke="#93c5fd" stroke-width="1"/>
+  <rect x="550" y="135" width="530" height="770" rx="0 0 8 8" fill="url(#implLaneGrad)" stroke="#fca5a5" stroke-width="1"/>
+
+  <!-- ==================== TASK: Human writes OpenAPI spec ==================== -->
+  <rect x="40" y="150" width="490" height="45" rx="22" fill="url(#taskGrad)" filter="url(#shadowSmall)"/>
+  <text x="285" y="178" text-anchor="middle" fill="#0e7490" font-size="12" font-weight="600">👤 Human writes OpenAPI spec</text>
+  
+  <!-- Arrow down -->
+  <line x1="285" y1="195" x2="285" y2="215" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== GATE 1: Change Allowlist ==================== -->
+  <rect x="40" y="225" width="490" height="70" rx="6" fill="white" stroke="#3b82f6" stroke-width="2" filter="url(#shadowSmall)"/>
+  <rect x="570" y="225" width="490" height="70" rx="6" fill="white" stroke="#ef4444" stroke-width="2" filter="url(#shadowSmall)"/>
+  
+  <text x="285" y="252" text-anchor="middle" fill="#1e40af" font-size="13" font-weight="600">Change Allowlist</text>
+  <rect x="60" y="262" width="200" height="24" rx="4" fill="#dbeafe" stroke="#3b82f6" stroke-width="1"/>
+  <text x="160" y="278" text-anchor="middle" fill="#1e40af" font-size="10">packages/** edit blocked</text>
+  <rect x="270" y="262" width="200" height="24" rx="4" fill="#dbeafe" stroke="#3b82f6" stroke-width="1"/>
+  <text x="370" y="278" text-anchor="middle" fill="#1e40af" font-size="10">*.generated.* edit blocked</text>
+
+  <text x="815" y="252" text-anchor="middle" fill="#991b1b" font-size="13" font-weight="600">Protected Paths</text>
+  <rect x="590" y="262" width="220" height="24" rx="4" fill="#fee2e2" stroke="#ef4444" stroke-width="1"/>
+  <text x="700" y="278" text-anchor="middle" fill="#991b1b" font-size="10">server/src/_shared/overlays/**</text>
+  <rect x="820" y="262" width="220" height="24" rx="4" fill="#fef3c7" stroke="#f59e0b" stroke-width="1"/>
+  <text x="930" y="278" text-anchor="middle" fill="#92400e" font-size="10">.github/** (approval req)</text>
+
+  <!-- Gate 1 badge (after boxes for z-index) -->
+  <rect x="515" y="246" width="70" height="28" rx="14" fill="#1e293b"/>
+  <text x="550" y="265" text-anchor="middle" fill="white" font-size="14" font-weight="bold">Gate 1</text>
+
+  <!-- Arrow down -->
+  <line x1="550" y1="295" x2="550" y2="315" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== GATE 2: OpenAPI Spec Validation ==================== -->
+  <rect x="40" y="325" width="490" height="70" rx="6" fill="white" stroke="#3b82f6" stroke-width="2" filter="url(#shadowSmall)"/>
+  <rect x="570" y="325" width="490" height="70" rx="6" fill="#f8fafc" stroke="#d1d5db" stroke-width="1" stroke-dasharray="4"/>
+  
+  <text x="285" y="352" text-anchor="middle" fill="#1e40af" font-size="13" font-weight="600">OpenAPI Spec Validation</text>
+  
+  <rect x="100" y="362" width="200" height="24" rx="4" fill="#dc2626"/>
+  <text x="200" y="378" text-anchor="middle" fill="white" font-size="9" font-weight="600">Spec Lint (Spectral)</text>
+  
+  <rect x="320" y="362" width="180" height="24" rx="4" fill="#f59e0b"/>
+  <text x="410" y="378" text-anchor="middle" fill="white" font-size="9" font-weight="600">Breaking Changes (oasdiff)</text>
+
+  <text x="815" y="365" text-anchor="middle" fill="#9ca3af" font-size="11" font-style="italic">No implementation checks at this gate</text>
+
+  <!-- Gate 2 badge (after boxes for z-index) -->
+  <rect x="515" y="346" width="70" height="28" rx="14" fill="#1e293b"/>
+  <text x="550" y="365" text-anchor="middle" fill="white" font-size="14" font-weight="bold">Gate 2</text>
+
+  <!-- Arrow down -->
+  <line x1="550" y1="395" x2="550" y2="415" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== GENERATOR ==================== -->
+  <rect x="200" y="425" width="700" height="50" rx="25" fill="url(#generatorGrad)" filter="url(#shadow)"/>
+  <text x="550" y="455" text-anchor="middle" fill="white" font-size="14" font-weight="600">micro-contracts generate: spec/** → packages/**</text>
+
+  <!-- Arrow down -->
+  <line x1="550" y1="475" x2="550" y2="495" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== GATE 3: Artifact Integrity ==================== -->
+  <rect x="40" y="505" width="490" height="115" rx="6" fill="white" stroke="#3b82f6" stroke-width="2" filter="url(#shadowSmall)"/>
+  <rect x="570" y="505" width="490" height="115" rx="6" fill="#f8fafc" stroke="#d1d5db" stroke-width="1" stroke-dasharray="4"/>
+  
+  <text x="285" y="532" text-anchor="middle" fill="#1e40af" font-size="13" font-weight="600">Generated Artifact Integrity</text>
+  
+  <rect x="60" y="542" width="140" height="24" rx="4" fill="#dc2626"/>
+  <text x="130" y="558" text-anchor="middle" fill="white" font-size="9" font-weight="600">Drift Check (git diff)</text>
+  
+  <rect x="210" y="542" width="140" height="24" rx="4" fill="#dc2626"/>
+  <text x="280" y="558" text-anchor="middle" fill="white" font-size="9" font-weight="600">Manifest Verification</text>
+  
+  <rect x="360" y="542" width="140" height="24" rx="4" fill="#dc2626"/>
+  <text x="430" y="558" text-anchor="middle" fill="white" font-size="9" font-weight="600">Package Typecheck (tsc)</text>
+  
+  <rect x="60" y="577" width="180" height="24" rx="4" fill="#dc2626"/>
+  <text x="150" y="593" text-anchor="middle" fill="white" font-size="9" font-weight="600">Project Rules (Spectral)</text>
+  
+  <rect x="250" y="577" width="250" height="24" rx="4" fill="#dc2626"/>
+  <text x="375" y="593" text-anchor="middle" fill="white" font-size="9" font-weight="600">Published Breaking Changes (oasdiff)</text>
+
+  <text x="815" y="565" text-anchor="middle" fill="#9ca3af" font-size="11" font-style="italic">No implementation checks at this gate</text>
+
+  <!-- Gate 3 badge (after boxes for z-index) -->
+  <rect x="515" y="549" width="70" height="28" rx="14" fill="#1e293b"/>
+  <text x="550" y="568" text-anchor="middle" fill="white" font-size="14" font-weight="bold">Gate 3</text>
+
+  <!-- Arrow down -->
+  <line x1="550" y1="620" x2="550" y2="640" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== TASK: AI/Human implements code ==================== -->
+  <rect x="570" y="650" width="490" height="45" rx="22" fill="url(#taskGrad)" filter="url(#shadowSmall)"/>
+  <text x="815" y="678" text-anchor="middle" fill="#0e7490" font-size="12" font-weight="600">🤖👤 AI or Human implements code</text>
+  
+  <!-- Arrow down from task -->
+  <line x1="815" y1="695" x2="815" y2="715" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== GATE 4: Code Quality ==================== -->
+  <rect x="40" y="735" width="490" height="70" rx="6" fill="#f8fafc" stroke="#d1d5db" stroke-width="1" stroke-dasharray="4"/>
+  <rect x="570" y="735" width="490" height="70" rx="6" fill="white" stroke="#ef4444" stroke-width="2" filter="url(#shadowSmall)"/>
+  
+  <text x="285" y="775" text-anchor="middle" fill="#9ca3af" font-size="11" font-style="italic">No spec checks at this gate</text>
+
+  <text x="815" y="762" text-anchor="middle" fill="#991b1b" font-size="13" font-weight="600">Code Quality</text>
+  
+  <rect x="590" y="772" width="110" height="24" rx="4" fill="#dc2626"/>
+  <text x="645" y="788" text-anchor="middle" fill="white" font-size="9" font-weight="600">TypeScript Lint (ESLint)</text>
+  
+  <rect x="710" y="772" width="100" height="24" rx="4" fill="#dc2626"/>
+  <text x="760" y="788" text-anchor="middle" fill="white" font-size="9" font-weight="600">Type Check (tsc)</text>
+  
+  <rect x="820" y="772" width="80" height="24" rx="4" fill="#dc2626"/>
+  <text x="860" y="788" text-anchor="middle" fill="white" font-size="9" font-weight="600">Unit Tests</text>
+  
+  <rect x="910" y="772" width="120" height="24" rx="4" fill="#f59e0b"/>
+  <text x="970" y="788" text-anchor="middle" fill="white" font-size="9" font-weight="600">Format Check (Prettier)</text>
+
+  <!-- Gate 4 badge (after boxes for z-index) -->
+  <rect x="515" y="756" width="70" height="28" rx="14" fill="#1e293b"/>
+  <text x="550" y="775" text-anchor="middle" fill="white" font-size="14" font-weight="bold">Gate 4</text>
+
+  <!-- Arrow down -->
+  <line x1="550" y1="805" x2="550" y2="825" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== GATE 5: Doc Consistency & Static Analysis ==================== -->
+  <rect x="40" y="835" width="490" height="70" rx="6" fill="white" stroke="#3b82f6" stroke-width="2" filter="url(#shadowSmall)"/>
+  <rect x="570" y="835" width="490" height="70" rx="6" fill="white" stroke="#ef4444" stroke-width="2" filter="url(#shadowSmall)"/>
+  
+  <text x="285" y="862" text-anchor="middle" fill="#1e40af" font-size="13" font-weight="600">Doc Consistency</text>
+  
+  <rect x="60" y="872" width="200" height="24" rx="4" fill="#dc2626"/>
+  <text x="160" y="888" text-anchor="middle" fill="white" font-size="9" font-weight="600">Markdown Sync (embedoc)</text>
+  
+  <rect x="270" y="872" width="120" height="24" rx="4" fill="#dc2626"/>
+  <text x="330" y="888" text-anchor="middle" fill="white" font-size="9" font-weight="600">Links Validity</text>
+
+  <text x="815" y="862" text-anchor="middle" fill="#991b1b" font-size="13" font-weight="600">Architectural Integrity</text>
+  
+  <rect x="690" y="872" width="250" height="24" rx="4" fill="#dc2626"/>
+  <text x="815" y="888" text-anchor="middle" fill="white" font-size="9" font-weight="600">Static Analysis (CodeQL)</text>
+
+  <!-- Gate 5 badge (after boxes for z-index) -->
+  <rect x="515" y="856" width="70" height="28" rx="14" fill="#1e293b"/>
+  <text x="550" y="875" text-anchor="middle" fill="white" font-size="14" font-weight="bold">Gate 5</text>
+
+  <!-- Arrow down -->
+  <line x1="550" y1="905" x2="550" y2="925" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== TASK: Human reviews docs/code ==================== -->
+  <rect x="40" y="935" width="1020" height="45" rx="22" fill="url(#taskGrad)" filter="url(#shadow)"/>
+  <text x="550" y="963" text-anchor="middle" fill="#0e7490" font-size="12" font-weight="600">👤 Human reviews docs &amp; code</text>
+
+  <!-- Arrow down -->
+  <line x1="550" y1="980" x2="550" y2="1000" stroke="#64748b" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- ==================== MERGE GATE ==================== -->
+  <rect x="40" y="1010" width="1020" height="55" rx="6" fill="url(#mergeGrad)" filter="url(#shadow)"/>
+  <text x="550" y="1035" text-anchor="middle" fill="white" font-size="15" font-weight="600">Merge Gate (All Required Status Checks Must Pass)</text>
+  <text x="550" y="1055" text-anchor="middle" fill="#bbf7d0" font-size="11">Gate 1 + Gate 2 + Gate 3 + Gate 4 + Gate 5 → PR can merge to main</text>
+
+  <!-- ==================== LEGEND ==================== -->
+  <rect x="40" y="1080" width="1020" height="95" rx="8" fill="white" stroke="#e2e8f0" stroke-width="1"/>
+  <text x="550" y="1105" text-anchor="middle" fill="#1e293b" font-size="14" font-weight="600">Legend</text>
+  
+  <!-- Severity legend -->
+  <rect x="60" y="1120" width="80" height="22" rx="4" fill="#dc2626"/>
+  <text x="100" y="1135" text-anchor="middle" fill="white" font-size="10" font-weight="600">ERROR</text>
+  <text x="155" y="1135" fill="#475569" font-size="10">Blocks merge</text>
+  
+  <rect x="230" y="1120" width="80" height="22" rx="4" fill="#f59e0b"/>
+  <text x="270" y="1135" text-anchor="middle" fill="white" font-size="10" font-weight="600">WARNING</text>
+  <text x="325" y="1135" fill="#475569" font-size="10">Advisory</text>
+  
+  <rect x="400" y="1120" width="80" height="22" rx="4" fill="#f8fafc" stroke="#d1d5db" stroke-width="1" stroke-dasharray="4"/>
+  <text x="440" y="1135" text-anchor="middle" fill="#9ca3af" font-size="10">Empty</text>
+  <text x="495" y="1135" fill="#475569" font-size="10">No checks</text>
+
+  <rect x="570" y="1120" width="80" height="22" rx="25" fill="url(#generatorGrad)"/>
+  <text x="610" y="1135" text-anchor="middle" fill="white" font-size="10" font-weight="600">Process</text>
+  <text x="665" y="1135" fill="#475569" font-size="10">Transformation</text>
+
+  <rect x="750" y="1120" width="80" height="22" rx="11" fill="url(#taskGrad)"/>
+  <text x="790" y="1135" text-anchor="middle" fill="#0e7490" font-size="10" font-weight="600">Task</text>
+  <text x="845" y="1135" fill="#475569" font-size="10">Human/AI work</text>
+
+  <!-- Lane description -->
+  <rect x="60" y="1150" width="16" height="12" rx="2" fill="#3b82f6"/>
+  <text x="85" y="1160" fill="#475569" font-size="10">Spec Level: OpenAPI contracts, generated artifacts, documentation</text>
+  
+  <rect x="550" y="1150" width="16" height="12" rx="2" fill="#ef4444"/>
+  <text x="575" y="1160" fill="#475569" font-size="10">Impl Level: TypeScript code, tests, static analysis (CodeQL)</text>
+
+</svg>

package/docs/overlays-deep-dive.md

@@ -0,0 +1,298 @@
+# OpenAPI Overlays (Deep Dive)
+
+> **Navigation**: [← Back to README](../README.md) | [Examples](../examples/)
+
+**Overlays** use the standard [OpenAPI Overlay Specification 1.0.0](https://www.openapis.org/blog/2024/10/22/announcing-overlay-specification) to define how `x-*` extensions transform the OpenAPI spec. This enables cross-cutting concerns (middleware, auth, rate limiting) without repeating definitions.
+
+**Why Overlays?**
+
+- **Standard format**: Uses official OpenAPI Overlay Specification — [learn more](https://learn.openapis.org/overlay/)
+- **Transparent transformation**: Clear what gets injected where
+- **Composable**: Chain multiple overlays (shared + module-specific)
+- **Tool compatibility**: Works with other Overlay-aware tools ([Redocly CLI](https://redocly.com/docs/cli/), etc.)
+
+---
+
+## How Overlays Work
+
+1. **Mark operations** with `x-middleware` (or custom extensions) in OpenAPI
+2. **Define overlay** that adds params/responses when extension is present
+3. **Generator applies overlays** and produces `openapi.generated.yaml`
+4. **Generate code** from the generated spec (types, routes, overlay interfaces)
+
+---
+
+## Overlay Scope
+
+| Scope | Overlay Location | Use Case |
+|-------|------------------|----------|
+| **Cross-module** | `spec/_shared/overlays/` | Auth, rate limiting, tenant isolation |
+| **Intra-module** | `spec/{module}/overlays/` | Module-specific validation (e.g., payment validation in billing) |
+
+---
+
+## Writing Overlay Definitions
+
+### 1. Mark Operations in OpenAPI
+
+Add extension markers to operations that need cross-cutting behavior:
+
+```yaml
+# spec/core/openapi/core.yaml
+paths:
+  /api/tenant/data:
+    get:
+      operationId: getTenantData
+      x-micro-contracts-domain: Tenant
+      x-micro-contracts-method: getTenantData
+      x-middleware:                        # ← Extension marker
+        - tenantIsolation
+        - requireAuth
+        - rateLimit
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TenantData'
+        # Note: 400, 401, 429 are NOT defined here
+        # They will be injected by the overlay
+```
+
+### 2. Define Overlay
+
+Create an overlay file that injects parameters and responses based on markers:
+
+```yaml
+# spec/_shared/overlays/middleware.overlay.yaml
+overlay: 1.0.0
+info:
+  title: Middleware Extension Overlay
+  version: 1.0.0
+
+actions:
+  # requireAuth: Inject Authorization header + 401 response
+  - target: "$.paths[*][*][?(@.x-middleware contains 'requireAuth')]"
+    x-micro-contracts-overlay-name: requireAuth  # ← Name for type generation
+    update:
+      parameters:
+        - name: Authorization
+          in: header
+          schema: { type: string }
+          description: Bearer token for authentication
+      responses:
+        '401':
+          $ref: '../openapi/problem-details.yaml#/components/responses/Unauthorized'
+
+  # tenantIsolation: Inject X-Tenant-Id header + 400 response
+  - target: "$.paths[*][*][?(@.x-middleware contains 'tenantIsolation')]"
+    x-micro-contracts-overlay-name: tenantIsolation
+    update:
+      parameters:
+        - name: X-Tenant-Id
+          in: header
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: Tenant identifier for multi-tenant isolation
+      responses:
+        '400':
+          description: Missing or invalid X-Tenant-Id header
+          content:
+            application/problem+json:
+              schema:
+                $ref: '../openapi/problem-details.yaml#/components/schemas/ProblemDetails'
+
+  # rateLimit: Inject 429 response with rate limit headers
+  - target: "$.paths[*][*][?(@.x-middleware contains 'rateLimit')]"
+    x-micro-contracts-overlay-name: rateLimit
+    update:
+      responses:
+        '429':
+          description: Too Many Requests
+          headers:
+            X-RateLimit-Limit:
+              schema: { type: integer }
+              description: Rate limit ceiling for this endpoint
+            Retry-After:
+              schema: { type: integer }
+              description: Seconds until rate limit resets
+```
+
+> **📦 Full example**: See [`examples/spec/_shared/overlays/middleware.overlay.yaml`](../examples/spec/_shared/overlays/middleware.overlay.yaml)
+
+### $ref Paths in Overlays
+
+Specify `$ref` paths **relative to the overlay file's location**. micro-contracts automatically rebases these paths so that the generated `openapi.generated.yaml` can resolve them correctly.
+
+```yaml
+# spec/_shared/overlays/middleware.overlay.yaml
+$ref: '../openapi/problem-details.yaml#/components/responses/Unauthorized'
+#      ↑ Resolves to spec/_shared/openapi/problem-details.yaml
+```
+
+**Rebase example:**
+
+| File | $ref path |
+|------|-----------|
+| Overlay (source) | `../openapi/problem-details.yaml#/...` |
+| Generated spec (`packages/contract/core/docs/openapi.generated.yaml`) | `../../../../spec/_shared/openapi/problem-details.yaml#/...` |
+
+The generated path is relative to `openapi.generated.yaml`'s location, ensuring the reference resolves correctly.
+
+---
+
+## Implementing Overlay Handlers
+
+Overlay handlers **do not directly access HTTP request/response objects** (e.g., Fastify's `req`/`reply`). Parameters are extracted by the generated adapter and passed as typed input. However, they are aware of HTTP concepts (header names, status codes) unlike Domain implementations which are purely business logic:
+
+```typescript
+// server/src/core/overlays/requireAuth.ts
+import type { 
+  RequireAuthOverlayInput, 
+  OverlayResult 
+} from '@project/contract/core/overlays/index.js';
+
+export async function requireAuth(input: RequireAuthOverlayInput): Promise<OverlayResult> {
+  const authHeader = input['Authorization'];
+  
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return {
+      success: false,
+      error: { status: 401, message: 'Missing or invalid authorization header' },
+    };
+  }
+
+  // In real app: validate JWT token and extract user info
+  return {
+    success: true,
+    context: { userId: 'user-123', role: 'user' },
+  };
+}
+```
+
+> **📦 Full examples**: See [`examples/server/src/core/overlays/`](../examples/server/src/core/overlays/)
+
+### Layer Responsibilities
+
+| Layer | Responsibility | Touches HTTP objects | Knows HTTP concepts |
+|-------|----------------|---------------------|---------------------|
+| **Generated routes** | Extract params, wire handlers | ✅ Yes | ✅ Yes |
+| **Overlay impl** | Handle cross-cutting concern | ❌ No | ✅ Yes (headers, status codes) |
+| **Domain impl** | Business logic only | ❌ No | ❌ No |
+
+---
+
+## Configuration
+
+Configure overlays in `micro-contracts.config.yaml`:
+
+```yaml
+# micro-contracts.config.yaml
+defaults:
+  overlays:
+    # Shared overlays applied to all modules (in order)
+    shared:
+      - spec/_shared/overlays/middleware.overlay.yaml
+    collision: error    # error | warn | last-wins (default: error)
+
+modules:
+  core:
+    openapi: openapi/core.yaml
+    overlays:  # Module-specific overlays (applied after shared)
+      - overlays/cache.overlay.yaml
+
+  billing:
+    openapi: openapi/billing.yaml
+    overlays:
+      - overlays/payment.overlay.yaml
+```
+
+---
+
+## Overlay Policies
+
+### 1. Collision Policy
+
+When multiple overlays inject the same key (e.g., `401` response):
+
+| Scenario | Policy | Rationale |
+|----------|--------|-----------|
+| Same key, **identical content** | ✅ Allow | No ambiguity |
+| Same key, **different content** | ❌ Error | Ambiguous intent |
+
+Configure in `defaults.overlays.collision`: `error` (default) | `warn` | `last-wins`
+
+### 2. Application Order
+
+Order is **deterministic**:
+
+```
+1. defaults.overlays.shared (in array order)
+2. modules.{name}.overlays (in array order)
+```
+
+Generation logs what was injected:
+
+```bash
+npx micro-contracts generate -m core
+
+[overlay] Applying spec/_shared/overlays/middleware.overlay.yaml
+  → /api/tenant/data GET: +X-Tenant-Id, +400, +401, +429
+[output] packages/contract/core/docs/openapi.generated.yaml
+```
+
+### 3. JSONPath Patterns
+
+micro-contracts uses a restricted JSONPath dialect for reliable parsing:
+
+| Pattern | Meaning |
+|---------|---------|
+| `$.paths[*][*]` | All operations |
+| `[?(@.x-ext)]` | Has extension |
+| `[?(@.x-ext contains 'value')]` | Array contains value |
+
+**Use `contains` for array membership:**
+
+```yaml
+# ✅ Correct - portable
+- target: "$.paths[*][*][?(@.x-middleware contains 'requireAuth')]"
+
+# ❌ Avoid - implementation-dependent
+- target: "$.paths[*][*][?(@.x-middleware[*] == 'requireAuth')]"
+```
+
+### 4. Marker vs Injection Responsibility
+
+| Layer | Responsibility |
+|-------|----------------|
+| **OpenAPI (source)** | Business responses (200, 201, 204) |
+| **OpenAPI (source)** | Extension markers (`x-middleware: [requireAuth]`) |
+| **Overlay** | Cross-cutting responses (400, 401, 403, 429) |
+
+**Anti-pattern**: Don't manually add `401` to operations that have `x-middleware: [requireAuth]`. Let the overlay inject it.
+
+---
+
+## Summary
+
+| What | Generated | Notes |
+|------|-----------|-------|
+| Overlay application | ✅ Yes | Transform OpenAPI (inject params/responses) |
+| Overlay interfaces | ✅ Yes | HTTP-agnostic (`OverlayRegistry`, `*OverlayInput`) |
+| Contract types | ✅ Yes | Types from OpenAPI schemas |
+| Route wiring | ✅ Via template | Template decides how to wire |
+| Overlay impl | ❌ Human | Implement generated interface |
+| Domain impl | ❌ Human | Business logic |
+
+---
+
+## Related Documentation
+
+| Document | Description |
+|----------|-------------|
+| **[Examples](../examples/)** | Complete working project with multiple modules and overlays |
+| **[Guardrails](development-guardrails.md)** | CI integration, security checks |
+| **[README](../README.md)** | Core concepts, configuration |

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "micro-contracts",
+  "version": "0.9.0",
+  "description": "Contract-first OpenAPI toolchain that keeps TypeScript UI and microservices aligned via code generation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "micro-contracts": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "generate": "tsx src/cli.ts generate",
+    "docs:sync": "npx embedoc build",
+    "docs:check": "npx embedoc build && git diff --exit-code README.md docs/",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "openapi",
+    "contract-first",
+    "microservices",
+    "code-generation",
+    "fastify",
+    "typescript",
+    "api",
+    "guardrails",
+    "ai-development"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/foo-ogawa/micro-contracts.git"
+  },
+  "homepage": "https://github.com/foo-ogawa/micro-contracts#readme",
+  "bugs": {
+    "url": "https://github.com/foo-ogawa/micro-contracts/issues"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "glob": "^10.3.10",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "embedoc": "^0.9.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}