@ibgib/space-gib 0.0.9 → 0.0.13

package/src/server/serve-gib/handlers/api/health.handler.mts

@@ -1,23 +0,0 @@
-/**
- * @module serve-gib/handlers/api/health
- */
-
-import { ServeGibHandlerBase } from '../handler-base.mjs';
-import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../types.mjs';
-import { API_PATH_REGEXES } from '../../../path-constants.mjs';
-
-/**
- * GET /api/health
- */
-export class HealthHandler extends ServeGibHandlerBase {
-    protected override method: ServeGibHttpMethod = 'ALL';
-    protected override regex = API_PATH_REGEXES.HEALTH;
-
-    protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
-        if (reqCtx.method === 'GET') {
-            return this.ok({ status: 'ok', timestamp: new Date().toISOString() });
-        } else {
-            throw new Error(`info.method !== 'GET' in ${HealthHandler.name} (E: bfff3c547b5827ca7845277804057f26)`);
-        }
-    }
-}

package/src/server/serve-gib/handlers/api/health.respec.mts

@@ -1,51 +0,0 @@
-import { respecfully, iReckon, ifWe, ifWeMight } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
-import { ServeGib_V1 } from '../../serve-gib-v1.mjs';
-import { HealthHandler } from './health.handler.mjs';
-import { ErrorHandler } from '../error-handler.mjs';
-
-const sir = `[${import.meta.url}]`;
-
-await respecfully(sir, 'Health Handler Integration', async () => {
-    const testDataDir = './test-data-health';
-    const port = 3002;
-
-    await ifWe(sir, 'get a 200 OK from /api/health', async () => {
-        // 1. Setup ServeGib_V1
-        const serveGib = new ServeGib_V1({
-            port,
-            dataDir: testDataDir,
-            handlers: [new HealthHandler()],
-            errorHandler: new ErrorHandler()
-        });
-
-        // 2. Mock GET Request
-        const req: any = {
-            url: '/api/health',
-            method: 'GET',
-            headers: {},
-            on: (event: string, cb: any) => {
-                if (event === 'end') { cb(); }
-            }
-        };
-
-        let capturedStatus: number = 0;
-        let capturedBody: any = null;
-        const res: any = {
-            writeHead: (status: number) => {
-                capturedStatus = status;
-            },
-            end: (body: string) => {
-                capturedBody = JSON.parse(body);
-            },
-            statusCode: 0
-        };
-
-        // 3. Handle
-        await serveGib.handleRequest(req, res);
-
-        // 4. Verify
-        iReckon(sir, capturedStatus).asTo('captured status code').isGonnaBe(200);
-        iReckon(sir, capturedBody.status).asTo('captured body status').isGonnaBe('ok');
-        iReckon(sir, capturedBody.timestamp).asTo('captured body timestamp').isGonnaBe(capturedBody.timestamp);
-    });
-});

package/src/server/serve-gib/handlers/api/ibgib/ibgib-handler-types.mts

@@ -1,49 +0,0 @@
-import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
-
-import { DomainInfo } from "../../../types.mjs";
-
-export interface IbGibParams {
-    domainInfo: DomainInfo;
-    ibGibIb: string;
-    ibGibGib: string;
-    ibGibAddr: IbGibAddr;
-}
-
-// #region IbGibGetQueryParams
-export const DEFAULT_QUERY_PARAMS_GET_IBGIB = {
-    /**
-     * If true, will get the latest ibgib.
-     */
-    getLatest: false, // Default to false for regular ibgibs
-    /**
-     * If true, will get the ibgib's entire dependency graph
-     */
-    getGraph: false, // Default to false for regular ibgibs
-    /**
-     * If true, returns only the resolved address (addr) rather than the full
-     * ibgib or graph body. Useful for a lightweight "tip check" before initiating
-     * a full sync: client compares `latestAddr` with its locally known addr.
-     *
-     * ## notes
-     *
-     * Typically combined with `getLatest: true` to ask "what is the server's
-     * current tip for this timeline?" without paying the cost of fetching the
-     * full ibgib body or graph.
-     *
-     * When `getLatest: false` and `addrOnly: true`, returns the addr as-is
-     * (i.e., confirms the given addr exists on the server).
-     */
-    addrOnly: false,
-};
-/**
- * @see {@link DEFAULT_QUERY_PARAMS_GET_IBGIB} key/values for jsdocs
- */
-export type IbGibGetQueryParams = Partial<typeof DEFAULT_QUERY_PARAMS_GET_IBGIB>;
-export type KNOWN_QUERY_PARAMS_IBGIB_GET = keyof IbGibGetQueryParams;
-export const KNOWN_QUERY_PARAMS_IBGIB_GET = Object.keys(DEFAULT_QUERY_PARAMS_GET_IBGIB) as KNOWN_QUERY_PARAMS_IBGIB_GET[];
-export function isKnownQueryParamsKey_IbGibGet(key: any): key is KNOWN_QUERY_PARAMS_IBGIB_GET {
-    return !!key && typeof key === 'string' ?
-        KNOWN_QUERY_PARAMS_IBGIB_GET.includes(key as any) :
-        false;
-}
-// #endregion IbGibGetQueryParams

package/src/server/serve-gib/handlers/api/ibgib/ibgib.handler.mts

@@ -1,176 +0,0 @@
-/**
- * @module serve-gib/handlers/api/ibgib
- */
-
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-
-import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
-import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
-import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
-import { validateAddressSegment } from '../../../../path-helper.mjs';
-import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
-import {
-    DEFAULT_QUERY_PARAMS_GET_IBGIB, IbGibGetQueryParams, IbGibParams,
-    isKnownQueryParamsKey_IbGibGet, KNOWN_QUERY_PARAMS_IBGIB_GET
-} from './ibgib-handler-types.mjs';
-import { validateAndCoerceBooleanQueryParam } from '../../../serve-gib-helpers.mjs';
-
-export interface IbGibGraphResponseBody {
-    addr: string;
-    count: number;
-    graph: Record<string, IbGib_V1>;
-}
-
-const logalot = GLOBAL_LOG_A_LOT;
-
-/**
- * GET /api/ibgib/:domainAddr/:ibGibAddr
- */
-export class IbGibHandler extends ServeGibHandlerWithMetaspaceBase<IbGibParams, IbGibGetQueryParams> {
-    protected override lc: string = `[${IbGibHandler.name}]`;
-    protected override method: ServeGibHttpMethod = 'GET';
-    protected override regex = API_PATH_REGEXES.IBGIB_ADDR;
-
-    protected override async parseParamsImpl(reqCtx: RequestContext<IbGibParams, IbGibGetQueryParams>): Promise<IbGibParams | undefined> {
-        const lc = `${this.lc}[${this.parseParamsImpl.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting...`); }
-            const match = reqCtx.pathname.match(this.regex);
-            if (!match) { throw new Error(`(UNEXPECTED) match falsy for regex? at this point, we have passed canHandleRoute, so this should parse correctly. (E: 8ce0810a3a88f420639bf8286df1d826)`); }
-            const domainIb = decodeURIComponent(match[1]);
-            const domainGib = decodeURIComponent(match[2]);
-            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
-            const ibGibIb = decodeURIComponent(match[3]);
-            const ibGibGib = decodeURIComponent(match[4]);
-            const ibGibAddr = getIbGibAddr({ ib: ibGibIb, gib: ibGibGib });
-            return {
-                ibGibIb, ibGibGib, ibGibAddr,
-                domainInfo: this.getDomainInfo({ domainAddr }),
-            };
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
-    protected override async validateQueryParams({ queryParams }: { queryParams: any; }): Promise<string[]> {
-        const lc = `${this.lc}[${this.validateQueryParams.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting...`); }
-
-            const errors: string[] = [];
-
-            // strict checking
-            const queryParamsKeys = Object.keys(queryParams);
-            const invalidKeys: string[] = queryParamsKeys.filter(x => !isKnownQueryParamsKey_IbGibGet(x));
-            if (invalidKeys.length > 0) {
-                throw new Error(`invalid query params keys: ${invalidKeys.join(', ')}. valid query params keys: ${KNOWN_QUERY_PARAMS_IBGIB_GET.join(', ')} (E: b7e8a9f2c1d34e56b89a01d4f2e7c326)`);
-            }
-
-            // Enforce that EVERY key must have a validation function mapping
-            type ValidationFn = () => Promise<void>;
-            const ValidationFns: Record<KNOWN_QUERY_PARAMS_IBGIB_GET, ValidationFn> = {
-                getLatest: async () => validateAndCoerceBooleanQueryParam(queryParams, 'getLatest', errors),
-                getGraph: async () => validateAndCoerceBooleanQueryParam(queryParams, 'getGraph', errors),
-                addrOnly: async () => validateAndCoerceBooleanQueryParam(queryParams, 'addrOnly', errors),
-            };
-
-            // execute all validation functions
-            for (const fn of Object.values(ValidationFns)) {
-                await fn();
-            }
-
-            return errors;
-
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
-    protected async handleRouteImpl(reqCtx: RequestContext<IbGibParams, IbGibGetQueryParams>): Promise<ResponseResult | undefined> {
-        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: 03d6a889b1f8af879c0f7158a3b3de26)`); }
-
-            if (logalot) { console.log(`${lc} starting... (I: 03d6a889b1f8af879c0f7158a3b3de26)`); }
-            if (!reqCtx.metaspace) { throw new Error(`(UNEXPECTED) metaspace falsy? we should have initialized it by now since this is a domain-dependent handler (E: 864661c668d2aa1918b7ee677a7d9c26)`); }
-
-            const { ibGibIb, ibGibGib } = reqCtx.params as IbGibParams;
-            if (!ibGibIb || !ibGibGib) { return undefined; }
-
-            // Reconstruct addr from params
-            const rawAddr = `${ibGibIb}^${ibGibGib}`;
-            if (!validateAddressSegment(rawAddr)) return this.error(400, 'Invalid address format');
-            const addr = rawAddr;
-
-            const queryParams = {
-                ...DEFAULT_QUERY_PARAMS_GET_IBGIB,
-                ...(reqCtx.queryParams ?? {}),
-            };
-
-            const { getLatest, getGraph, addrOnly } = queryParams;
-
-            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
-            if (!space) { throw new Error(`(UNEXPECTED) couldn't get default local user space? (E: ec6161ea3a08892ad8bfd1b7b0d79826)`); }
-
-            let addr_latest: string = addr;
-            if (getLatest) {
-                const latestAddr = await reqCtx.metaspace.getLatestAddr({ addr, space });
-                if (latestAddr) { addr_latest = latestAddr; }
-            }
-
-            // Lightweight tip-check: return only the resolved address.
-            // Client uses this to decide whether a full sync is necessary
-            // without incurring the cost of fetching the full ibgib or graph.
-            if (addrOnly && !getGraph) {
-                return this.ok({ addr: addr_latest, clientAddr: addr });
-            } /* <<<<< returns early */
-
-            if (getGraph) {
-                const resGraph = await reqCtx.metaspace.getDependencyGraph({
-                    ibGibAddr: addr_latest,
-                    space,
-                    live: getLatest,
-                });
-                const addrs = Object.keys(resGraph);
-                if (addrs.length > 0) {
-                    if (addrOnly) {
-                        // Return only the address list for delta negotiation (smart diff):
-                        // client compares these against what it already has to determine
-                        // the minimal set it needs to fetch.
-                        return this.ok({ addr: addr_latest, clientAddr: addr, addrs });
-                    } else {
-                        const responseBody: IbGibGraphResponseBody = {
-                            addr: addr_latest,
-                            count: addrs.length,
-                            graph: resGraph
-                        };
-                        return this.ok(responseBody);
-                    }
-                } else {
-                    return this.notFound(`Graph not found for ${addr_latest} (E: 89b259f13ae5e4f0d8287f6c0475a826)`);
-                }
-            } else {
-                const resGet = await reqCtx.metaspace.get({ space, addr: addr_latest });
-                if (resGet.success && resGet.ibGibs?.length === 1) {
-                    const ibGib = resGet.ibGibs[0];
-                    return this.ok(ibGib);
-                } else {
-                    return this.notFound(`IbGib not found for ${addr_latest} (E: 017621e0a8086832ff06cfc884b8c426)`);
-                }
-            }
-        } catch (error) {
-            if (logalot) { console.error(extractErrorMsg(error)) }
-            return this.error(500, extractErrorMsg(error));
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-}

package/src/server/serve-gib/handlers/api/keystone/keystone-evolve.handler.mts

@@ -1,150 +0,0 @@
-/**
- * @module serve-gib/handlers/api/keystone/keystone-evolve.handler
- *
- * PUT /api/keystone/evolve/:domainAddr
- *
- * Receives an evolved domain keystone (`I^I1.Itjp`) and any related
- * ibgibs (e.g., the `S^Stjp` session keystone).
- *
- * Validates the evolution, verifies the `S` session keystone, and persists
- * them to the domain metaspace to authorize the sync session.
- */
-
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { validateAndRegisterEvolveKeystone } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
-import { KeystoneIbGib_V1 } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
-import { loadSsoServerConfig } from '@ibgib/web-gib/dist/identity/sso/sso-config-helper.mjs';
-import { SsoCustodianService } from '@ibgib/web-gib/dist/identity/sso/sso-custodian-service.mjs';
-
-import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
-import { ServeGibHandlerWithMetaspaceBase } from '../../handler-base.mjs';
-import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
-import { ParamsWithDomain, RequestContext, ResponseResult } from '../../../types.mjs';
-
-const logalot = GLOBAL_LOG_A_LOT || true;
-
-interface EvolveParams extends ParamsWithDomain {
-    domainAddr: string;
-}
-
-/**
- * Body payload for the Keystone Evolve REST API request.
- */
-interface EvolveBody {
-    /** The main evolved keystone frame. */
-    keystoneIbGib: KeystoneIbGib_V1;
-    /**
-     * Array of other keystone frames related to this evolution.
-     * Ephemeral session keystones for sync, or persistent delegate keystones for manage.
-     */
-    relatedKeystoneIbGibs?: IbGib_V1[];
-    /** Optional map of providerId to token to revoke during unlinking. */
-    revokeTokens?: Record<string, string>;
-}
-
-export class KeystoneEvolveHandler extends ServeGibHandlerWithMetaspaceBase<EvolveParams, EvolveBody> {
-    protected override lc: string = `[${KeystoneEvolveHandler.name}]`;
-    protected override method: 'PUT' = 'PUT';
-    protected override regex = API_PATH_REGEXES.KEYSTONE_EVOLVE;
-
-    protected override async parseParamsImpl(reqCtx: RequestContext<EvolveParams, any>): Promise<EvolveParams | undefined> {
-        const match = reqCtx.pathname.match(this.regex);
-        if (match && match.length >= 3) {
-            const domainIb = decodeURIComponent(match[1]);
-            const domainGib = decodeURIComponent(match[2]);
-            const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
-            return {
-                domainAddr,
-                domainInfo: this.getDomainInfo({ domainAddr })
-            };
-        } else {
-            return undefined;
-        }
-    }
-
-    protected override async validateQueryParams({ queryParams }: { queryParams: any; }): Promise<string[]> {
-        return []; // We don't expect any query parameters for evolution
-    }
-
-    protected override async handleRouteImpl(reqCtx: RequestContext<EvolveParams>): Promise<ResponseResult> {
-        const lc = `${this.lc}[handleRouteImpl]`;
-        try {
-            if (logalot) { console.log(`${lc} starting...`); }
-
-            if (!reqCtx.params) { return this.error(400, 'Invalid parameters'); }
-            if (!reqCtx.metaspace) { return this.error(500, 'Metaspace not initialized'); }
-
-            const { domainAddr } = reqCtx.params;
-            const bodyStr = reqCtx.body;
-            if (!bodyStr) { return this.error(400, 'Empty body'); }
-
-            let parsed: EvolveBody;
-            try {
-                parsed = JSON.parse(bodyStr);
-            } catch (err) {
-                return this.error(400, 'Invalid request JSON body: bodyStr does NOT parse. (E: 2f81c8c80a6884ff32b877671e92f326)');
-            }
-
-            const { keystoneIbGib, relatedKeystoneIbGibs = [] } = parsed;
-            if (!keystoneIbGib) {
-                return this.error(400, 'Invalid request. Body must contain keystoneIbGib (E: e234647f79282982c8012fe8015f5826)');
-            }
-
-            const space = await reqCtx.metaspace.getLocalUserSpace({ lock: false });
-            if (!space) {
-                return this.error(500, 'No local user space found (E: a1144e5d6cd9641fb82d6b359f131126)');
-            }
-
-            // Delegate all intrinsic checks, transition rules, pool restrictions, and registration/persistence to core-gib helper
-            await validateAndRegisterEvolveKeystone({
-                domainAddr,
-                keystoneIbGib,
-                relatedKeystoneIbGibs,
-                metaspace: reqCtx.metaspace,
-                space
-            });
-
-            // Post-Evolution Hook: Handle SSO provider unlinking
-            const claim = keystoneIbGib.data?.proofs?.[0]?.claim;
-            if (claim?.details?.type === 'remove-pool') {
-                const removeInfo = claim.details.info;
-                if (removeInfo && Array.isArray(removeInfo.remove)) {
-                    // Lazy-load custodian service config
-                    const config = loadSsoServerConfig();
-                    const custodian = new SsoCustodianService(config);
-
-                    for (const poolId of removeInfo.remove) {
-                        if (poolId.startsWith('custodian-manage-')) {
-                            const providerId = poolId.replace('custodian-manage-', '');
-                            console.log(`${lc} Evolved keystone removed custodian pool: ${poolId}. Performing unlink cleanup for provider: ${providerId}`);
-
-                            // Revoke token if supplied by the client
-                            const token = parsed.revokeTokens?.[providerId];
-                            if (token) {
-                                try {
-                                    await custodian.revokeToken(providerId as any, token);
-                                } catch (e) {
-                                    console.warn(`${lc} Failed to revoke token for provider ${providerId}: ${extractErrorMsg(e)}`);
-                                }
-                            } else {
-                                console.log(`${lc} No OAuth token supplied by client for revocation of provider: ${providerId}`);
-                            }
-                        }
-                    }
-                }
-            }
-
-            return this.ok({
-                message: `Successfully evolved domain keystone with session keystone`,
-            });
-
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            return this.error(422, `Evolve validation/persistence failed: ${extractErrorMsg(error)}`);
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-}

package/src/server/serve-gib/handlers/api/keystone/keystone-genesis.handler.mts

@@ -1,146 +0,0 @@
-/**
- * @module serve-gib/handlers/api/keystone/keystone-genesis.handler
- *
- * POST /api/keystone/genesis
- *
- * Accepts a single genesis-frame keystone ibgib from the client and
- * bootstraps a new domain-isolated metaspace for it.
- *
- * ## request body
- *
- * ```json
- * { "keystoneIbGib": <KeystoneIbGib_V1> }
- * ```
- *
- * ## validation steps
- *
- * 1. Body contains `keystoneIbGib` (single ibgib, not an array).
- * 2. Intrinsic hash validation passes (`validateIbGibIntrinsically`).
- * 3. Structural keystone check: `ib` starts with `"keystone"`, no `past` in
- *    `rel8ns` (genesis = TJP frame, no prior timeline).
- * 4. Domain uniqueness: the path derived from the keystone's tjpGib must not
- *    already exist on disk — if it does, return 409 Conflict.
- * 5. Bootstrap: call `bootstrapDomainMetaspace` to create folders + metaspace.
- * 6. Persist the keystone ibgib into the newly created domain space.
- *
- * ## notes
- *
- * Unlike domain-scoped handlers, this handler does NOT rely on
- * `reqCtx.metaspace` (which is undefined when no domain exists yet). It
- * creates the metaspace itself using `bootstrapDomainMetaspace`.
- */
-
-import { existsSync } from 'node:fs';
-
-import { extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
-import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
-import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
-
-import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
-import { ServeGibHandlerBase } from '../../handler-base.mjs';
-import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
-import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
-import { getDomainRootPath } from '../../../../bootstrap-helper.mjs';
-import { bootstrapDomainMetaspace } from '../../../../bootstrap-helper.mjs';
-
-const logalot = GLOBAL_LOG_A_LOT || true;
-
-
-
-
-/**
- * POST /api/keystone/genesis
- *
- * No path params — the domain is derived from the incoming keystone ibgib.
- */
-export class KeystoneGenesisHandler extends ServeGibHandlerBase<undefined, undefined> {
-    protected override lc: string = `[${KeystoneGenesisHandler.name}]`;
-    protected override method: ServeGibHttpMethod = 'POST';
-    protected override regex = API_PATH_REGEXES.KEYSTONE_GENESIS;
-
-    protected async handleRouteImpl(
-        reqCtx: RequestContext<undefined, undefined>
-    ): Promise<ResponseResult | undefined> {
-        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c526)`); }
-
-            // ----------------------------------------------------------------
-            // 1. Parse body — expect { keystoneIbGib }
-            // ----------------------------------------------------------------
-            let parsed: any;
-            try {
-                parsed = JSON.parse(reqCtx.body);
-            } catch {
-                return this.error(400, 'Request body must be valid JSON (E: dd8618857568f8fc5e9c62b8ed135826)');
-            }
-
-            const { keystoneIbGib } = parsed;
-            if (!keystoneIbGib) {
-                return this.error(400, 'Body must contain keystoneIbGib (E: 9c8c5d979d7842cd716ba64f69349c26)');
-            }
-
-            // ----------------------------------------------------------------
-            // 2. Intrinsic hash validation
-            // ----------------------------------------------------------------
-            const intrinsicErrors = await validateIbGibIntrinsically({ ibGib: keystoneIbGib });
-            if (intrinsicErrors) {
-                return this.error(422, 'Intrinsic keystone validation failed (E: 76d388e198f23a87dd6596f59c36e826)', { errors: intrinsicErrors });
-            }
-
-            // ----------------------------------------------------------------
-            // 3. Structural keystone + genesis-frame checks
-            // ----------------------------------------------------------------
-            const keystoneService = new KeystoneService_V1();
-            const keystoneErrors = await keystoneService.validateGenesisKeystone({
-                keystoneIbGib
-            });
-            if (keystoneErrors && keystoneErrors.length > 0) {
-                return this.error(422, `Keystone genesis validation failed. Errors: ${keystoneErrors} (E: 8384285be7a8ab0d41cfd1df2e2aa826)`, { errors: keystoneErrors });
-            }
-
-            // ----------------------------------------------------------------
-            // 4. Domain uniqueness check — 409 if the domain already exists
-            // ----------------------------------------------------------------
-            const addr = getIbGibAddr({ ibGib: keystoneIbGib });
-            const { tjpGib, punctiliarHash } = getGibInfo({ ibGibAddr: addr });
-            const domainGib = tjpGib || punctiliarHash;
-            if (!domainGib) {
-                return this.error(422, `Could not extract domain identifier from keystone address: ${addr} (E: 2758588a6d7cc77f078e97989feed326)`);
-            }
-
-            const domainRootPath = getDomainRootPath(domainGib, reqCtx.dataDir);
-            if (existsSync(domainRootPath)) {
-                return this.error(409, `Domain already exists for this keystone (tjpGib: ${domainGib}). Use PUT /api/keystone/evolve/:domainAddr to evolve. (E: 1c56c8885781c86df89cbdfc1b310626)`);
-            }
-
-            // ----------------------------------------------------------------
-            // 5. Bootstrap the new domain metaspace (creates folders)
-            // ----------------------------------------------------------------
-            const metaspace = await bootstrapDomainMetaspace(addr, reqCtx.dataDir);
-
-            // ----------------------------------------------------------------
-            // 6. Persist the genesis keystone into the new domain space
-            // ----------------------------------------------------------------
-            const space = await metaspace.getLocalUserSpace({ lock: false });
-            if (!space) {
-                throw new Error(`(UNEXPECTED) Could not get local user space after bootstrapping domain for ${addr} (E: b1c2d3e4f5a6b7c8d9e0f1a2b3c4d526)`);
-            }
-
-            await metaspace.put({ ibGibs: [keystoneIbGib], space });
-            await metaspace.registerNewIbGib({ ibGib: keystoneIbGib, space });
-
-            console.log(`${lc} domain created and keystone persisted: ${addr}`);
-            // if (logalot) { console.log(`${lc} keystoneIbGib: ${pretty(keystoneIbGib)} (I: d598c6ff7a48997d585b84c19c464826)`); }
-            return this.ok({ success: true, addr }, 201);
-        } catch (error) {
-            const emsg = extractErrorMsg(error);
-            console.error(`${lc} ${emsg}`);
-            return this.error(500, emsg);
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-}