The MVP is a polished single-player hackathon experience. Its strict TypeScript engine is the sole authority over gameplay, while AI output passes schema, policy, registry, and bounded-effect validation before it can influence a turn.

Generative games are creative, but they become unreliable when the same model also acts as the rules engine. A model can forget state, invent mechanics, contradict an earlier turn, or make an unfair call.

RuleShift AI separates those responsibilities. Gemini may propose narration, choices, items, and a known temporary rule; a seeded TypeScript engine alone calculates health, energy, damage, score, inventory, objectives, and outcomes. The experience stays surprising without surrendering fairness or continuity.

Every completed turn exposes a player-facing resolution receipt showing the creative source, deterministic state changes, active RuleShift behavior, and the safety boundary that was enforced.

The application uses Next.js App Router, strict TypeScript, Tailwind CSS, customized shadcn/ui primitives, PostgreSQL with Prisma, and a provider-neutral AI boundary currently implemented with Gemini.

Generated text is parsed, schema-validated, policy-checked, converted into bounded proposals, and then applied by registered deterministic behavior. No AI response is executed as code and no provider can directly set final state.

flowchart LR
    subgraph client ["Client"]
        browser["Player browser"]
    end
    subgraph gateway ["Vercel edge"]
        nextRoutes["Next.js routes"]
    end
    subgraph service ["Application runtime"]
        gameApp["RuleShift AI service"]
    end
    subgraph datastore ["Persistent state"]
        postgres["PostgreSQL"]
    end
    subgraph external ["Optional creative provider"]
        gemini["Gemini API"]
    end

    browser -->|"HTTPS"| nextRoutes
    nextRoutes -->|"Validated commands"| gameApp
    gameApp -->|"Atomic sessions"| postgres
    gameApp -.->|"Gemini: structured proposals"| gemini

sequenceDiagram
    title One authoritative player turn
    participant Browser
    participant RouteHandler
    participant GameService
    participant Engines
    participant AIDirector
    participant PostgreSQL

    Browser->>RouteHandler: POST action and expected version
    RouteHandler->>RouteHandler: Validate origin, body, and owner
    RouteHandler->>GameService: Authenticated command
    GameService->>PostgreSQL: Load session or idempotent replay
    PostgreSQL-->>GameService: Owned session snapshot
    GameService->>Engines: Resolve deterministic preview
    GameService->>AIDirector: Request structured event
    AIDirector-->>GameService: Validated event or fallback
    GameService->>Engines: Apply approved event and rules
    GameService->>PostgreSQL: Commit snapshots and replay record
    PostgreSQL-->>GameService: Committed state version
    GameService-->>RouteHandler: Validated next state
    RouteHandler-->>Browser: Safe response

stateDiagram-v2
    direction LR
    [*] --> Playing
    Playing --> Playing: valid turn
    Playing --> Victory: objective and reward complete
    Playing --> Defeat: terminal condition reached
    Playing --> Abandoned: owner abandons
    Victory --> [*]
    Defeat --> [*]
    Abandoned --> [*]

erDiagram
    direction LR
    GAME_SESSION ||--o{ GAME_EVENT : records
    GAME_SESSION ||--o{ ACTIVE_RULE : activates
    GAME_SESSION ||--o{ INVENTORY_ITEM : contains
    GAME_SESSION ||--o{ NPC_STATE : tracks
    GAME_SESSION ||--o{ TURN_REQUEST : deduplicates

    GAME_SESSION {
        uuid id PK
        string ownerTokenHash
        string status
        int stateVersion
        int currentTurn
        json currentSnapshot
    }
    GAME_EVENT {
        uuid id PK
        uuid sessionId FK
        int turn
        json beforeStateSnapshot
        json afterStateSnapshot
    }
    ACTIVE_RULE {
        uuid id PK
        uuid sessionId FK
        string ruleKey
        int remainingTurns
    }
    INVENTORY_ITEM {
        uuid id PK
        uuid sessionId FK
        string itemId
        int quantity
    }
    NPC_STATE {
        uuid id PK
        uuid sessionId FK
        string npcId
        int relationship
    }
    TURN_REQUEST {
        uuid id PK
        uuid sessionId FK
        string idempotencyKey
        int resultingVersion
    }

See ARCHITECTURE.md for trust boundaries, request flows, ownership, persistence, and deployment topology.

The prepared demo follows Devesh, the Placement Warrior, through the Haunted Campus of Infinite Assessments toward the Golden Offer Letter. The interface is responsive, keyboard-accessible, screen-reader aware, reduced-motion safe, and fully understandable while muted.

• Node.js 24 LTS
• npm 10 or newer
• PostgreSQL 15 or newer
• Chromium for Playwright browser tests
• Optional Gemini API key and model identifier

1. Clone the repository and install the exact locked dependency graph:

   npm ci

2. Copy .env.example to .env.local. Keep real values out of chat, source, screenshots, logs, and commits.

3. Configure a local or dedicated development PostgreSQL connection:

   DATABASE_URL=postgresql://USER:PASSWORD@HOST/DATABASE?sslmode=verify-full
   AI_PROVIDER_MODE=fallback

4. Confirm the target is a development database, then apply migrations:

   npm run db:migrate:dev

5. Start the application:

   npm run dev

6. Open http://localhost:3000 and confirm /api/health returns HTTP 200.

For Neon, use a pooled connection string from the Neon Console. The server normalizes legacy strict SSL modes to verify-full. Do not point automated tests at a shared development or production database.

No environment variable is prefixed with NEXT_PUBLIC_; credentials are never included in browser bundles. Missing Gemini configuration automatically selects the deterministic fallback path.

1. Create or select a Gemini API project in Google AI Studio.

2. Store the credential as GEMINI_API_KEY in .env.local for development or in encrypted hosting environment settings for deployment.

3. Store the chosen model identifier as GEMINI_MODEL; it is deliberately not hardcoded.

4. Set AI_PROVIDER_MODE=gemini.

5. Run the opt-in live provider smoke only when external access is authorized:

   npm run test:ai:live

The smoke test uses one validated provider-generated event in a complete game, then proves deterministic fallback continuity. It does not log prompts, provider responses, or credentials.

• Development: npm run db:migrate:dev refuses production-like targets.

• Test: npm run db:migrate:test requires TEST_DATABASE_URL and rejects production-like database names.

• Staging/production: back up and identify the target, then run:

  npm run db:migrate:deploy -- --confirm-database=EXACT_DATABASE_NAME

The deployment wrapper refuses to proceed unless the confirmation exactly matches the database name parsed from DATABASE_URL. Migrations are never run automatically during next build.

No production seed is required. Each new session is created through the validated session API, so seeding cannot overwrite player data.

Testing details and isolation rules live in TESTING.md.

RuleShift AI was built through ten approval-gated Codex phases rather than a single code-generation pass. The repository preserves the phase branches, commits, verification commands, architectural decisions, fallback strategy, and review loops.

• Built with Codex documents what Codex planned, implemented, verified, and corrected in each phase.
• First-time usability study provides a no-coaching protocol and evidence table for five external playtests. Results must be recorded only after real sessions; the repository does not fabricate them.

The repository is compatible with Vercel without vercel.json; Next.js route handlers, timeouts, and security headers are already expressed in application code. Deployment is intentionally manual and approval-gated.

See DEPLOYMENT.md for free-tier constraints, environment configuration, staging migration, smoke verification, rollback, logging, observability, and the exact approval checklist.

• Anonymous ownership uses a cryptographically random secure HTTP-only cookie; only its SHA-256 hash is stored.
• Mutations require same-origin requests, bounded JSON bodies, Zod validation, optimistic versions, idempotency keys, and rate limiting.
• Authoritative turns persist atomically with before/after snapshots.
• AI proposals pass JSON parsing, schema validation, content policy, rule registry validation, and deterministic bounded-effect conversion.
• Errors expose themed safe messages; internal logs contain classifications, not connection strings, owner tokens, prompts, or provider responses.
• Security headers disable framing, MIME sniffing, camera, microphone, and geolocation while applying a strict referrer policy.

The included rate limiter is per runtime instance and suitable as a basic hackathon abuse guard. It is not a distributed quota. A higher-risk public launch should add platform WAF/rate rules or a shared limiter before accepting untrusted high-volume traffic.