# Implementation Plan: Modular Policy Schemas & Keystone Profile Builder

This document outlines the step-by-step development tasks to transition the Keystone policy engine to a modular JSON-schema composed architecture with a fluent builder.

Parent Architecture Doc: [ARCHITECTURE.md](../../../../../docs/identity/ARCHITECTURE.md)

---

## 📋 Task Checklist

- [x] **1. Modular JSON Schema & Profiles Definitions**
  - [x] Create schemas: `sync-pool.schema.json`, `manage-pool.schema.json`, `revoke-pool.schema.json`, `connect-pool.schema.json`, `sign-pool.schema.json` under `libs/core-gib/src/keystone/policy/schemas/`.
  - [x] Define composite schemas `keystone.high.schema.json`, `keystone.medium.schema.json`, `keystone.low.schema.json`.
  - [x] Migrate JSON profile files to use new schema locations.

- [x] **2. Type System Refactoring**
  - [x] Update [keystone-policy-types.mts](../keystone-policy-types.mts) to support composite profiles and new metadata schemas.

- [x] **3. Implement `KeystoneProfileBuilder`**
  - [x] Create `keystone-profile-builder.mts` inside `libs/core-gib/src/keystone/policy/`.
  - [x] Implement `buildKeystone`, `withUsername`, `withEmail`, `withDescription`, `withDetails`.
  - [x] Implement `customizePool` and `compileConfigs` with unique salt derivation and `frameDetails` unification.

- [x] **4. Build Pipeline Integration**
  - [x] Update `build-core-gib.mts` to copy new schema/profile directories to `dist`.

- [x] **5. Downstream Consumption Refactoring**
  - [x] Refactor space-gib's `keystone-creator.mts` to use the new builder.

- [x] **6. Automated Verification**
  - [x] Add integration tests in `keystone-service-v1.respec.mts` ensuring the builder and modular schemas are correctly parsed, validated, and applied.

- [x] **7. Documentation & Architecture Sync**
  - [x] Update [ARCHITECTURE.md](../../../../../docs/identity/ARCHITECTURE.md) with corrected code snippets (including fluent builder code samples) and clickable links to the actual code files (like schemas and builder implementation) for reference.

---

## 🛠️ Build & Verification Guide

Use the following commands from the monorepo root to build and verify your changes:

### 1. Build core-gib
Check if core-gib compiles clean:
```powershell
npm run build:core-gib
```

### 2. Monorepo Chain Build
Build all libraries and compile the downstream `space-gib` application to test integration:
```powershell
npm run chain:build:core-gib
```

### 3. Run Space-Gib Client
To manually test the Keystone creation process via the space-gib UI, run:
```powershell
npm run dev:space-gib
```


