@ibgib/core-gib 0.1.59 → 0.1.61

package/src/keystone/keystone-service-v1.respec.mts

@@ -12,7 +12,8 @@ import { KeystoneChallengePool, KeystoneClaim, KeystoneIbGib_V1, KeystonePoolCon
 import { createRevocationPoolConfig, createStandardPoolConfig } from './keystone-config-builder.mjs';
 import { POOL_ID_DEFAULT, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE } from './keystone-constants.mjs';
 import { KeystoneService_V1 } from './keystone-service-v1.mjs';
-import { addToBindingMap } from './keystone-helpers.mjs';
+import { selectChallengeIds, validateChallengePool } from './keystone-helpers.mjs';
+import { KeystoneProfileBuilder } from './policy/keystone-profile-builder.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -131,7 +132,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Derivation Logic', async () => {
 
-        await ifWe(sir, 'derivePoolSecret with same inputs returns same output', async () => {
+        await ifWeMight(sir, 'derivePoolSecret with same inputs returns same output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -141,7 +142,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secret length').isGonnaBeTruthy();
         });
 
-        await ifWe(sir, 'derivePoolSecret with different master secret returns different output', async () => {
+        await ifWeMight(sir, 'derivePoolSecret with different master secret returns different output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -150,7 +151,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secrets differ').not.willEqual(secretB);
         });
 
-        await ifWe(sir, 'derivePoolSecret with different salt returns different output', async () => {
+        await ifWeMight(sir, 'derivePoolSecret with different salt returns different output', async () => {
             // Modify salt in a copy of config
             const configB = { ...config, salt: "OtherPool" };
             const strategyA = KeystoneStrategyFactory.create({ config });
@@ -165,7 +166,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Challenge/Solution Logic', async () => {
 
-        await ifWe(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
+        await ifWeMight(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "a3ff7843552870fc28bef2b"; // arbitrary random challengeId
@@ -184,7 +185,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('valid pair should pass').isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'validateSolution fails for mismatched values', async () => {
+        await ifWeMight(sir, 'validateSolution fails for mismatched values', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "8c994f3ed598f150e25513"; // arbitrary random challengeId
@@ -200,7 +201,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('tampered solution should fail').isGonnaBeFalse();
         });
 
-        await ifWe(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
+        await ifWeMight(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
 
@@ -241,7 +242,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Genesis', async () => {
-        await ifWe(sir, 'creates a valid genesis frame and persists it', async () => {
+        await ifWeMight(sir, 'creates a valid genesis frame and persists it', async () => {
             const salt = (await getUUID()).substring(0, 16);
             const config = createStandardPoolConfig({
                 id: POOL_ID_DEFAULT,
@@ -273,7 +274,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Signing (Evolution)', async () => {
-        await ifWe(sir, 'evolves the keystone with a valid proof', async () => {
+        await ifWeMight(sir, 'evolves the keystone with a valid proof', async () => {
             const claim: Partial<KeystoneClaim> = {
                 target: "comment 123^gib",
                 verb: "post"
@@ -303,7 +304,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Validation', async () => {
-        await ifWe(sir, 'validates the genesis->signed transition', async () => {
+        await ifWeMight(sir, 'validates the genesis->signed transition', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: signedKeystone,
@@ -352,7 +353,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Wrong Secret (Forgery)', async () => {
-        await ifWe(sir, 'prevents creation of forged frames', async () => {
+        await ifWeMight(sir, 'prevents creation of forged frames', async () => {
             const claim: Partial<KeystoneClaim> = { target: "comment 123^gib", verb: "post" };
 
             let errorCaught = false;
@@ -381,7 +382,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Policy Violation (Restricted Verbs)', async () => {
-        await ifWe(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
+        await ifWeMight(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
             // Create a specific restricted pool config manually
             const restrictedPoolId = "read_only_pool";
             const restrictedConfig = createStandardPoolConfig({
@@ -461,7 +462,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
     await respecfully(sir, 'Revoke Lifecycle', async () => {
         let revokedKeystone: KeystoneIbGib_V1;
 
-        await ifWe(sir, 'successfully creates a revocation frame', async () => {
+        await ifWeMight(sir, 'successfully creates a revocation frame', async () => {
             revokedKeystone = await service.revoke({
                 latestKeystone: genesisKeystone,
                 masterSecret,
@@ -479,7 +480,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, data.revocationInfo!.proof.claim.verb).willEqual(KEYSTONE_VERB_REVOKE);
         });
 
-        await ifWe(sir, 'validates the revocation frame', async () => {
+        await ifWeMight(sir, 'validates the revocation frame', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: revokedKeystone!,
@@ -490,7 +491,7 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, errors.length).asTo('no validation errors').willEqual(0);
         });
 
-        await ifWe(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
+        await ifWeMight(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
             const data = revokedKeystone!.data!;
             const revokePool = data.challengePools.find(p => p.id === POOL_ID_REVOKE);
 
@@ -528,7 +529,6 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
         const strategy = KeystoneStrategyFactory.create({ config });
         const poolSecret = await strategy.derivePoolSecret({ masterSecret: bobSecret });
         const challenges: { [id: string]: any } = {};
-        const bindingMap: { [char: string]: string[] } = {};
 
         for (let i = 0; i < 10; i++) {
             // Manually replicate ID gen for test
@@ -540,14 +540,12 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             });
             const challenge = await strategy.generateChallenge({ solution });
             challenges[challengeId] = challenge;
-            addToBindingMap(bindingMap, challengeId);
         }
 
         return {
             id,
             config,
             challenges,
-            bindingMap,
             isForeign: true,
             metadata: { owner: 'Bob' }
         };
@@ -569,7 +567,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -608,7 +606,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone
             let id = "read_only";
             const restrictedConfig = createStandardPoolConfig({ id, salt: id });
@@ -641,7 +639,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'fails on ID collision', async () => {
+        await ifWeMight(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -688,7 +686,6 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
         const strategy = KeystoneStrategyFactory.create({ config });
         const poolSecret = await strategy.derivePoolSecret({ masterSecret: bobSecret });
         const challenges: { [id: string]: any } = {};
-        const bindingMap: { [char: string]: string[] } = {};
 
         // Generate a small set of challenges
         for (let i = 0; i < 10; i++) {
@@ -700,14 +697,12 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             });
             const challenge = await strategy.generateChallenge({ solution });
             challenges[challengeId] = challenge;
-            addToBindingMap(bindingMap, challengeId);
         }
 
         return {
             id,
             config,
             challenges,
-            bindingMap,
             isForeign: true,
             metadata: { owner: 'Bob', role: 'Delegate' }
         };
@@ -732,7 +727,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Happy Path', async () => {
-        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
+        await ifWeMight(sir, 'authorizes and adds a foreign pool', async () => {
             const bobPool = await createForeignPool("pool_bob", ["post"]);
 
             const updatedKeystone = await service.addPools({
@@ -771,7 +766,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
     });
 
     await respecfully(sir, 'Permissions & Logic', async () => {
-        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
+        await ifWeMight(sir, 'fails if no pool allows "manage" verb', async () => {
             // 1. Create a restricted keystone (read-only)
             let id = "read_only";
             const restrictedConfig = createStandardPoolConfig({ id, salt: id });
@@ -804,7 +799,7 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
             iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
         });
 
-        await ifWe(sir, 'fails on ID collision', async () => {
+        await ifWeMight(sir, 'fails on ID collision', async () => {
             // Try to add "pool_bob" again (it was added in Happy Path)
             const duplicatePool = await createForeignPool("pool_bob");
 
@@ -866,7 +861,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
     await respecfully(sir, 'Proof Granularity & Math', async () => {
 
-        await ifWe(sir, 'generates exactly the expected number of solutions', async () => {
+        await ifWeMight(sir, 'generates exactly the expected number of solutions', async () => {
             signedKeystone = await service.sign({
                 latestKeystone: genesisKeystone,
                 masterSecret: aliceSecret,
@@ -883,7 +878,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, solutions.length).asTo('solution count').willEqual(4);
         });
 
-        await ifWe(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
+        await ifWeMight(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
             const proof = signedKeystone.data!.proofs[0];
             const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === poolId)!;
 
@@ -912,7 +907,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             }
         });
 
-        await ifWe(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
+        await ifWeMight(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
             const proof = signedKeystone.data!.proofs[0];
             const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === poolId)!;
 
@@ -930,11 +925,75 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, hasFirst).asTo(`Solution includes 1st FIFO ID (${expectedFifoIds[0]})`).isGonnaBeTrue();
             iReckon(sir, hasSecond).asTo(`Solution includes 2nd FIFO ID (${expectedFifoIds[1]})`).isGonnaBeTrue();
         });
+
+        await ifWeMight(sir, 'verifies Next-Gen Hash-Based Target Binding Selection', async () => {
+            const bindingConfig = createStandardPoolConfig({
+                id: "binding_pool",
+                salt: "binding_salt",
+                sequential: 0,
+                random: 0,
+                targetBinding: 3,
+                size: 20
+            }) as KeystonePoolConfig_HashV1;
+
+            const tempGenesis = await service.genesis({
+                masterSecret: aliceSecret,
+                configs: [bindingConfig],
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            // Evolve using the binding pool
+            const evolved = await service.sign({
+                latestKeystone: tempGenesis,
+                masterSecret: aliceSecret,
+                poolId: "binding_pool",
+                claim: {
+                    verb: "sign",
+                    target: "some_target_address^gib"
+                },
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            const proof = evolved.data!.proofs[0];
+            iReckon(sir, proof.solutions.length).asTo('proof solutions count').willEqual(3);
+
+            // Now, let's verify that the selection is perfectly deterministic.
+            // If we run selectChallengeIds manually with the same pool and target, it must return the same IDs.
+            const poolSnapshot = tempGenesis.data!.challengePools.find(p => p.id === "binding_pool")!;
+            const selectedIds = await selectChallengeIds({
+                pool: poolSnapshot,
+                targetAddr: "some_target_address^gib"
+            });
+
+            const proofIds = proof.solutions.map(s => s.challengeId);
+            iReckon(sir, selectedIds.length).asTo('selected IDs count').willEqual(3);
+            for (const id of selectedIds) {
+                iReckon(sir, proofIds.includes(id)).asTo(`proof includes selected ID ${id}`).isGonnaBeTrue();
+            }
+        });
+
+        await ifWeMight(sir, 'fails validation if total requested challenges >= size', async () => {
+            const invalidConfig = createStandardPoolConfig({
+                id: "invalid_pool",
+                salt: "invalid_salt",
+                sequential: 5,
+                random: 5,
+                targetBinding: 6,
+                size: 15 // total requested is 5+5+6 = 16 >= 15
+            });
+
+            const errors = await validateChallengePool({ pool: { id: "invalid_pool", config: invalidConfig, challenges: {} } });
+            iReckon(sir, errors.length > 0).asTo('errors length is positive').isGonnaBeTrue();
+            const hasCorrectError = errors.some(e => e.includes("Total requested challenges"));
+            iReckon(sir, hasCorrectError).asTo('validation error content').isGonnaBeTrue();
+        });
     });
 
     await respecfully(sir, 'DTO & Serialization', async () => {
 
-        await ifWe(sir, 'survives a clone/JSON-cycle without corruption', async () => {
+        await ifWeMight(sir, 'survives a clone/JSON-cycle without corruption', async () => {
             // 1. Create a DTO (simulate network transmission/storage)
             // 'clone' does a JSON stringify/parse under the hood (usually) or structured clone.
             const dto = clone(signedKeystone);
@@ -954,7 +1013,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
             iReckon(sir, errors.length).asTo('DTO validation errors').willEqual(0);
         });
 
-        await ifWe(sir, 'ensures data contains no functions or circular refs', async () => {
+        await ifWeMight(sir, 'ensures data contains no functions or circular refs', async () => {
             // A crude but effective test: ensure JSON.stringify doesn't throw
             // and the result is equal to the object (if we parsed it back).
 
@@ -978,4 +1037,127 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
         });
 
     });
+
+    await respecfully(sir, 'KeystoneProfileBuilder and Modular Schemas', async () => {
+
+        await ifWeMight(sir, 'compiles configs successfully with medium profile', async () => {
+            const builder = KeystoneProfileBuilder.buildKeystone('medium')
+                .withUsername('alice')
+                .withEmail('alice@example.com')
+                .withDescription('Alice test keystone')
+                .withDetails({ extraInfo: 'abc' });
+
+            const configs = await builder.compileConfigs();
+            iReckon(sir, configs.length).asTo('number of pools').willEqual(5);
+
+            // Verify unique salt derivation per pool
+            const salts = configs.map(c => c.salt);
+            const uniqueSalts = new Set(salts);
+            iReckon(sir, uniqueSalts.size).asTo('unique salts count').willEqual(5);
+
+            // Verify frameDetails unification
+            const details = builder.getFrameDetails();
+            iReckon(sir, details.username).asTo('username').willEqual('alice');
+            iReckon(sir, details.email).asTo('email').willEqual('alice@example.com');
+            iReckon(sir, details.description).asTo('description').willEqual('Alice test keystone');
+            iReckon(sir, details.extraInfo).asTo('extraInfo').willEqual('abc');
+        });
+
+        await ifWeMight(sir, 'supports customized overrides', async () => {
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .customizePool('sync', {
+                    behavior: {
+                        size: 15,
+                        targetBindingCount: 4
+                    }
+                });
+
+            const configs = await builder.compileConfigs();
+            const syncPool = configs.find(c => c.id === 'sync')!;
+            iReckon(sir, syncPool.behavior.size).asTo('customized size').willEqual(15);
+            iReckon(sir, syncPool.behavior.targetBindingCount).asTo('customized target binding').willEqual(4);
+        });
+
+    });
+
+    await respecfully(sir, 'Keystone Metadata Validation', async () => {
+
+        await ifWeMight(sir, 'validates correct username and description', async () => {
+            const service = new KeystoneService_V1();
+            const space = new MockIbGibSpace();
+            const metaspace = new MockMetaspaceService(space);
+
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .withUsername('alice_123.test')
+                .withDescription('Valid description: yes, it is!')
+                .withDetails({ client: 'respec' });
+
+            const configs = await builder.compileConfigs();
+            const frameDetails = builder.getFrameDetails();
+
+            // Should succeed without error
+            const keystoneIbGib = await service.genesis({
+                masterSecret: 'mysecret',
+                configs,
+                metaspace: metaspace as any,
+                space: space as any,
+                frameDetails
+            });
+
+            const errors = await service.validateGenesisKeystone({ keystoneIbGib });
+            iReckon(sir, errors.length).asTo('errors count').willEqual(0);
+        });
+
+        await ifWeMight(sir, 'fails validation for invalid username length or character', async () => {
+            const service = new KeystoneService_V1();
+            const space = new MockIbGibSpace();
+            const metaspace = new MockMetaspaceService(space);
+
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .withUsername('invalid_user_name_that_is_way_too_long_for_the_sixty_three_char_limit_and_will_fail_regex_check')
+                .withDetails({ client: 'respec' });
+
+            const configs = await builder.compileConfigs();
+            const frameDetails = builder.getFrameDetails();
+
+            const keystoneIbGib = await service.genesis({
+                masterSecret: 'mysecret',
+                configs,
+                metaspace: metaspace as any,
+                space: space as any,
+                frameDetails
+            });
+
+            const errors = await service.validateGenesisKeystone({ keystoneIbGib });
+            iReckon(sir, errors.length).asTo('errors count').willEqual(1);
+            iReckon(sir, errors[0]).includes('invalid username');
+        });
+
+        await ifWeMight(sir, 'fails validation for invalid description characters', async () => {
+            const service = new KeystoneService_V1();
+            const space = new MockIbGibSpace();
+            const metaspace = new MockMetaspaceService(space);
+
+            const builder = KeystoneProfileBuilder.buildKeystone('test')
+                .withUsername('alice')
+                .withDescription('Invalid desc with weird emoji 🚀')
+                .withDetails({ client: 'respec' });
+
+            const configs = await builder.compileConfigs();
+            const frameDetails = builder.getFrameDetails();
+
+            const keystoneIbGib = await service.genesis({
+                masterSecret: 'mysecret',
+                configs,
+                metaspace: metaspace as any,
+                space: space as any,
+                frameDetails
+            });
+
+            const errors = await service.validateGenesisKeystone({ keystoneIbGib });
+            iReckon(sir, errors.length).asTo('errors count').willEqual(1);
+            iReckon(sir, errors[0]).includes('invalid description');
+        });
+
+    });
 });

package/src/keystone/keystone-types.mts

@@ -111,10 +111,12 @@ export interface KeystonePoolBehavior {
     selectRandomly: number;
 
     /**
-     * Number of hex characters from the Target's Gib to match.
+     * Number of challenges to draw deterministically from the pool using
+     * next-gen hash-based index selection (drawing without replacement)
+     * bound to the full target address (`ib` + `gib`).
      * @default 0
      */
-    targetBindingChars: number;
+    targetBindingCount: number;
 }
 
 export interface KeystonePoolConfigBase {
@@ -227,13 +229,7 @@ export interface KeystoneChallengePool {
      */
     challenges: { [challengeId: string]: KeystoneChallenge };
 
-    /**
-     * Explicit Buckets for Target Binding.
-     * Key: Hex Character ('0'-'f').
-     * Value: Array of Challenge IDs that satisfy this bucket.
-     * Note: A single ID may appear in multiple buckets (Coverage Strategy).
-     */
-    bindingMap: { [hexChar: string]: string[] };
+
 
     /**
      * If true, this pool's secrets are NOT derived from the Keystone's

package/src/keystone/policy/IMPLEMENTATION.md

@@ -0,0 +1,60 @@
+# 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
+```
+
+

package/src/keystone/policy/README.md

@@ -0,0 +1,94 @@
+# Keystone Identity Policies & Fluent Builder
+
+This module manages Keystone Identity Policies, including security preset profiles (`high`, `medium`, `low`), modular schema composition, and the fluent configuration builder.
+
+---
+
+## 📖 Documentation Index
+
+*   **[Policy Architecture](../../../../../docs/identity/ARCHITECTURE.md)**: Conceptual design of separate pool behaviors, verbs, and composed schemas.
+*   **[Implementation Roadmap](./IMPLEMENTATION.md)**: Current development checklist and tasks.
+
+---
+
+## 🛠️ Usage: Fluent Builder API
+
+The `KeystoneProfileBuilder` provides a fluid interface to construct, enrich, and customize Keystone configurations before genesis.
+
+### Basic Identity Creation
+
+```typescript
+import { KeystoneProfileBuilder } from "@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs";
+
+// Build a medium-security identity config salted for a specific user
+const configs = KeystoneProfileBuilder
+    .buildKeystone('medium')
+    .withUsername('alice')
+    .withEmail('alice@example.com')
+    .withDescription('Main user identity for Space-Gib')
+    .compileConfigs();
+
+// Pass these configurations directly to genesis
+const identity = await keystoneService.genesis({
+    masterSecret,
+    configs,
+    metaspace,
+    space
+});
+```
+
+### Unifying Identity Details
+
+The metadata provided to `withUsername`, `withEmail`, `withDescription`, and `withDetails` are automatically consolidated into the unified `frameDetails` field of the genesis frame:
+
+```typescript
+const configs = KeystoneProfileBuilder
+    .buildKeystone('low')
+    .withUsername('bob')
+    .withDetails({
+        device: 'Pixel 8 Pro',
+        os: 'Android 14'
+    })
+    .compileConfigs();
+```
+
+### Runtime Customizations
+
+If an application needs to customize a specific pool's parameters dynamically (for example, raising KDF hash rounds on the sync pool for higher-security environments), use `customizePool`:
+
+```typescript
+const configs = KeystoneProfileBuilder
+    .buildKeystone('medium')
+    .withUsername('charlie')
+    .customizePool('sync', {
+        rounds: 5, // Override base medium profile rounds
+    })
+    .compileConfigs();
+```
+
+---
+
+## ⚠️ TypeScript & JSON Config Integration
+
+If downstream projects import or load their own JSON configurations (e.g., custom `.json` files representing schemas or behavior configurations) rather than relying solely on the built-in profiles, TypeScript requires explicit path tracking in projects using `"composite": true`.
+
+To prevent compiler errors like `TS6307: File '...' is not listed within the file list...`, ensure your project's `tsconfig.json` contains:
+
+1. `"resolveJsonModule": true` under `compilerOptions` to allow static importing of JSON files as ES modules.
+2. The folder/wildcard path of the JSON files added to the `"include"` array. For example:
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "resolveJsonModule": true,
+    "module": "ESNext"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.mts",
+    "src/custom-policies/*.json"
+  ]
+}
+```
+