@ibgib/core-gib 0.1.48 → 0.1.50

package/src/sync/sync-peer/sync-peer-http-receiver/sync-http-node-adapter.mts

@@ -0,0 +1,319 @@
+import * as http2 from 'http2';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { SyncPeerHttpReceiver_V1 } from './sync-peer-http-receiver-v1.mjs';
+import { SyncSagaContextIbGib_V1 } from '../../sync-saga-context/sync-saga-context-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface SyncHttpNodeAdapterOpts {
+    /** The receiver peer to route sync traffic to */
+    receiverPeer: SyncPeerHttpReceiver_V1;
+    /** The port to listen on. Defaults to 8080. */
+    port?: number;
+    /**
+     * Base path for the sync routes. Defaults to '/sync'.
+     * Will expose `/sync/frame` (POST) and `/sync/events` (GET).
+     */
+    basePath?: string;
+    /** TLS/SSL Private Key (needed for secure HTTP/2) */
+    key?: string | Buffer;
+    /** TLS/SSL Certificate (needed for secure HTTP/2) */
+    cert?: string | Buffer;
+    /** TLS/SSL PFX file (alternative to key/cert on Windows) */
+    pfx?: string | Buffer;
+    /** Passphrase for TLS/SSL PFX file */
+    passphrase?: string;
+}
+
+/**
+ * A basic Node HTTP adapter for the Symmetric Sync Protocol.
+ *
+ * Handles establishing the SSE EventSource stream (GET /sync/events)
+ * and receiving the Uplink (POST /sync/frame).
+ *
+ * NOTE: This is built using Node's standard `http` module. In a real
+ * production app (e.g. `node-gib` or a consumer app), you might adapt this
+ * to Express, Fastify, or directly to an HTTP/2 server.
+ */
+export class SyncHttpNodeAdapter_V1 {
+    protected lc: string = `[${SyncHttpNodeAdapter_V1.name}]`;
+
+    protected server?: http2.Http2Server | http2.Http2SecureServer;
+    protected receiverPeer: SyncPeerHttpReceiver_V1;
+    protected port: number;
+    protected basePath: string;
+
+    /**
+     * Map of clientId to their active Server-Sent Events HTTP Response streams.
+     */
+    protected activeSseStreams = new Map<string, http2.Http2ServerResponse>();
+
+    constructor(public opts: SyncHttpNodeAdapterOpts) {
+        this.receiverPeer = opts.receiverPeer;
+        this.port = opts.port || 8080;
+        this.basePath = opts.basePath || '/sync';
+    }
+
+    /**
+     * Starts the HTTP Server listening on the configured port.
+     */
+    public async start(): Promise<void> {
+        const lc = `[${this.start.name}]`;
+        return new Promise((resolve, reject) => {
+            try {
+                if (logalot) { console.log(`${lc} starting... (I: fc09bcef98bda9d91429161355c2e626)`); }
+                const requestHandler = (req: http2.Http2ServerRequest, res: http2.Http2ServerResponse) => {
+                    this.handleRequest(req, res).catch(e => {
+                        console.error(`${lc} Uncaught request error: ${extractErrorMsg(e)}`);
+                        if (!res.headersSent) {
+                            res.writeHead(500);
+                            res.end('Internal Server Error');
+                        }
+                    });
+                };
+
+                // Use Secure Server if TLS credentials are provided, otherwise fallback to unencrypted (h2c)
+                if ((this.opts.key && this.opts.cert) || this.opts.pfx) {
+                    const secureOpts: http2.SecureServerOptions = {
+                        allowHTTP1: true // Fallback to HTTP/1.1 for clients that don't support HTTP/2
+                    };
+                    if (this.opts.key) secureOpts.key = this.opts.key;
+                    if (this.opts.cert) secureOpts.cert = this.opts.cert;
+                    if (this.opts.pfx) secureOpts.pfx = this.opts.pfx;
+                    if (this.opts.passphrase) secureOpts.passphrase = this.opts.passphrase;
+
+                    this.server = http2.createSecureServer(secureOpts, requestHandler);
+                } else {
+                    this.server = http2.createServer({}, requestHandler);
+                }
+
+                this.server.listen(this.port, () => {
+                    const protocol = ((this.opts.key && this.opts.cert) || this.opts.pfx) ? 'https/h2' : 'http/h2c';
+                    if (logalot) { console.log(`${lc} Server listening on port ${this.port} (${protocol}) (I: 67a5ce98074c5aaaff022f5b3804c226)`); }
+                    resolve();
+                });
+            } catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                reject(error);
+            } finally {
+                if (logalot) { console.log(`${lc} complete. (I: 1d9e40501e6c191b186ae32edf151526)`); }
+            }
+        });
+    }
+
+    /**
+     * Stops the HTTP Server and closes all active streams.
+     */
+    public async stop(): Promise<void> {
+        const lc = `[${this.stop.name}]`;
+        return new Promise((resolve, reject) => {
+            try {
+                if (logalot) { console.log(`${lc} starting... (I: d7bca060bb02a9fa0cbd4fb65971fb26)`); }
+                for (const res of this.activeSseStreams.values()) {
+                    res.end(); // close all open streams
+                }
+                this.activeSseStreams.clear();
+
+                if (this.server) {
+                    this.server.close((err) => {
+                        if (err) return reject(err);
+                        resolve();
+                    });
+                } else {
+                    resolve();
+                }
+            } catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                reject(error);
+            } finally {
+                if (logalot) { console.log(`${lc} complete. (I: afa81c5b3a3f88fb6fe0066dd096ff26)`); }
+            }
+        });
+    }
+
+    protected async handleRequest(req: http2.Http2ServerRequest, res: http2.Http2ServerResponse) {
+        const lc = `${this.lc}[${this.handleRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 286853cd380d13292d2d36171ca11a26)`); }
+            // Set basic CORS headers for browser clients
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+
+            const url = new URL(req.url || '/', `http://${req.headers.host}`);
+
+            // Route: GET /sync/events
+            if (req.method === 'GET' && url.pathname.startsWith(`${this.basePath}/events`)) {
+                return this.handleSseStreamRequest(req, res, url);
+            }
+
+            // Route: POST /sync/frame
+            if (req.method === 'POST' && url.pathname.startsWith(`${this.basePath}/frame`)) {
+                return this.handleSyncFrameRequest(req, res, url);
+            }
+
+            res.writeHead(404);
+            res.end('Not Found');
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected async handleSseStreamRequest(req: http2.Http2ServerRequest, res: http2.Http2ServerResponse, url: URL) {
+        const lc = `${this.lc}[${this.handleSseStreamRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 17800c6b501b3b07436303e97b930626)`); }
+
+            // Get clientId from query param, or generate one
+            const clientId = url.searchParams.get('clientId') || Math.random().toString(36).substring(2, 10);
+
+            if (logalot) { console.log(`${lc} New SSE Connection: ${clientId} (I: c1ebeeb91763b76ed0a64cf8af7c6326)`); }
+
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive'
+            });
+
+            // Register the stream
+            this.activeSseStreams.set(clientId, res);
+
+            // Keep connection alive
+            const keepAliveInterval = setInterval(() => {
+                res.write(`:\n\n`); // comment line
+            }, 30000);
+
+            req.on('close', () => {
+                if (logalot) { console.log(`${lc} SSE Connection Closed: ${clientId} (I: 44aea766eb8b7279e5d9cf699a12cb26)`); }
+                clearInterval(keepAliveInterval);
+                this.activeSseStreams.delete(clientId);
+            });
+
+            // Send an initial connected message (optional)
+            res.write(`data: ${JSON.stringify({ type: 'connected', clientId })}\n\n`);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected async handleSyncFrameRequest(req: http2.Http2ServerRequest, res: http2.Http2ServerResponse, url: URL) {
+        const lc = `${this.lc}[${this.handleSyncFrameRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: fee247b53b894f2b6cf3f1f2d4dec726)`); }
+            // Assume the client ID is passed via query param or header
+            const clientId = url.searchParams.get('clientId') || req.headers['x-client-id'] as string;
+
+            if (!clientId) {
+                res.writeHead(400);
+                res.end('clientId required');
+                return;
+            }
+
+            const streamRes = this.activeSseStreams.get(clientId);
+            if (!streamRes) {
+                res.writeHead(400);
+                res.end(`No active SSE stream found for clientId: ${clientId}`);
+                return;
+            }
+
+            // 1. Parse incoming POST body
+            const body = await this.readRequestBody(req);
+
+            // TODO [USER]: Deserialize your incoming JSON request body into the expected IbGib variables
+            const parsedBody = JSON.parse(body);
+
+            // EXPECTED TYPES:
+            const context: SyncSagaContextIbGib_V1 = parsedBody.context;
+            const controlIbGibs: any[] = parsedBody.controlIbGibs || [];
+
+            // 2. Hand it off to the HTTP Receiver Peer
+            if (logalot) { console.log(`${lc} Handling Incoming Sync Request from ${clientId} (I: d89d3d28a418d9f6b261b61a164bd326)`); }
+            const responseContext = await this.receiverPeer.handleIncomingSyncRequest({
+                context,
+                controlIbGibs
+            });
+
+            if (!responseContext) {
+                res.writeHead(200);
+                res.end('OK - No Response Context');
+                return;
+            }
+
+            // 3. We successfully processed it and got a responseContext.
+            // Now, we must stream the response down the `streamRes` (SSE Connection).
+
+            // Stream Domain IbGibs first
+            if (responseContext.payloadIbGibsDomain) {
+                for (const domainIbGib of responseContext.payloadIbGibsDomain) {
+                    // TODO [USER]: Serialize Domain IbGib for transport
+                    const payloadChunk = JSON.stringify({
+                        type: 'domain',
+                        ibGib: domainIbGib
+                    });
+                    streamRes.write(`data: ${payloadChunk}\n\n`);
+                }
+                // Clean it up so we don't send the entire domain payload list again in the control context
+                delete responseContext.payloadIbGibsDomain;
+            }
+
+            // Stream Control Context response
+            // TODO [USER]: Serialize Response Context for transport
+            const contextChunk = JSON.stringify({
+                type: 'context',
+                context: responseContext
+            });
+            streamRes.write(`data: ${contextChunk}\n\n`);
+
+            // Ack the POST request
+            res.writeHead(200);
+            res.end('OK');
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            res.writeHead(500);
+            res.end(`Internal Server Error`);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected readRequestBody(req: http2.Http2ServerRequest): Promise<string> {
+        const lc = `${this.lc}[${this.readRequestBody.name}]`;
+        return new Promise((resolve, reject) => {
+            try {
+                if (logalot) { console.log(`${lc} starting... (I: 95cf4f489e1b7174dc5294096c651326)`); }
+                let body = '';
+                req.on('data', chunk => {
+                    body += chunk.toString();
+                });
+                req.on('end', () => {
+                    resolve(body);
+                });
+                req.on('error', (err) => {
+                    console.error(`${lc} ${extractErrorMsg(err)}`);
+                    reject(err);
+                });
+            } catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                reject(error);
+            } finally {
+                if (logalot) { console.log(`${lc} complete.`); }
+            }
+        });
+    }
+}

package/src/sync/sync-peer/sync-peer-http-receiver/sync-http-node-adapter.mts.metadata.md

@@ -0,0 +1,72 @@
+# agent refactor metadata
+
+## guidelines
+
+* **Imports Order & logalot**:
+  * Imports should be organized in the following order:
+    1. non-@ibgib external dependencies
+    2. blank line
+    3. @ibgib external dependencies (order: helper-gib, ts-gib, encrypt-gib, core-gib, node-gib, web-gib)
+    4. blank line
+    5. `import { GLOBAL_LOG_A_LOT } from '../path/to/constants/file.mts';` (if applicable)
+    6. other local file imports
+    7. blank line
+    8. `const logalot = GLOBAL_LOG_A_LOT` (if applicable)
+    9. blank line
+  * So the `GLOBAL_LOG_A_LOT` is a local import, and this should be first iif the file contains any functions with logging.
+* **Destructured params and logging**:
+  * Use destructured arguments for functions (unless it's an extremely small helper with a single obvious param).
+  * Harness most functions with `try/catch/finally` blocks and logging using `if (logalot)`.
+  * Define `const lc = \`[${functionName.name}]\`;` at the top of the function.
+  * In the `catch` block, explicitly log using `console.error(\`${lc} ${extractErrorMsg(error)}\`);` and `throw error;` (Do NOT add a UUID here).
+  * For Promises, include a `reject` inside the catch block.
+* **Tag Logging Messages with UUIDs**:
+  * Tag ALL logging messages, warnings, and errors with the proper prefix (e.g., I:, W:, E:) and a uuid inside parens, e.g., `(I: cfe7c7f220c84bd832bad493a9453826)`. Note: we will use `generate-id.js` for this.
+
+## libs/core-gib/src/sync/sync-peer/sync-peer-http-receiver/sync-http-node-adapter.mts
+
+[changes will go here]
+
+### 2026/02/27 - 10:17 AM
+
+#### line 1 - Imports Order & logalot
+
+```typescript
+import * as http2 from 'http2';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { SyncPeerHttpReceiver_V1 } from './sync-peer-http-receiver-v1.mjs';
+import { SyncSagaContextIbGib_V1 } from '../../sync-saga-context/sync-saga-context-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+```
+
+#### lines 55-274 - Destructured params and logging / Tag Logging Messages
+
+```typescript
+    // Wrapped functions matching the try/catch/finally logging pattern:
+    public async start(): Promise<void> { ... }
+    public async stop(): Promise<void> { ... }
+    protected async handleRequest(...) { ... }
+    protected async handleSseStreamRequest(...) { ... }
+    protected async handleSyncFrameRequest(...) { ... }
+    protected readRequestBody(...) { ... }
+
+    // Example of changes applied to methods:
+    public async start(): Promise<void> {
+        const lc = `[${this.start.name}]`;
+        return new Promise((resolve, reject) => {
+            try {
+                if (logalot) { console.log(`${lc} starting... (I: fc09bcef98bda9d91429161355c2e626)`); }
+                // ...
+            } catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                reject(error);
+            } finally {
+                if (logalot) { console.log(`${lc} complete. (I: 1d9e40501e6c191b186ae32edf151526)`); }
+            }
+        });
+    }
+```

package/src/sync/sync-peer/sync-peer-http-receiver/sync-peer-http-receiver-types.mts

@@ -0,0 +1,30 @@
+/**
+ * @module sync-peer-http-receiver-types
+ */
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness, InitializeSyncPeerOpts } from '../sync-peer-types.mjs';
+import { MetaspaceService } from '../../../witness/space/metaspace/metaspace-types.mjs';
+import { SyncSagaCoordinator } from '../../sync-saga-coordinator.mjs';
+import { IbGibSpaceAny } from '../../../witness/space/space-base-v1.mjs';
+
+/**
+ * Data for the SyncPeerHttpReceiver witness.
+ */
+export interface SyncPeerHttpReceiverData_V1 extends SyncPeerData_V1 {
+}
+
+/**
+ * Relations for the SyncPeerHttpReceiver witness.
+ */
+export interface SyncPeerHttpReceiverRel8ns_V1 extends SyncPeerRel8ns_V1 {
+}
+
+/**
+ * The SyncPeerHttpReceiver witness IbGib.
+ */
+export interface SyncPeerHttpReceiverIbGib_V1 extends IbGib_V1<SyncPeerHttpReceiverData_V1, SyncPeerHttpReceiverRel8ns_V1> { }
+
+export interface InitializeSyncPeerHttpReceiverOpts extends InitializeSyncPeerOpts {
+    localCoordinator: SyncSagaCoordinator;
+    localMetaspace: MetaspaceService;
+}

package/src/sync/sync-peer/sync-peer-http-receiver/sync-peer-http-receiver-v1.mts

@@ -0,0 +1,146 @@
+/**
+ * @module sync-peer-http-receiver-v1
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { SyncPeer_V1 } from '../sync-peer-v1.mjs';
+import { SyncSagaContextIbGib_V1 } from '../../sync-saga-context/sync-saga-context-types.mjs';
+import { IbGibSpaceAny } from '../../../witness/space/space-base-v1.mjs';
+import {
+    InitializeSyncPeerHttpReceiverOpts,
+    SyncPeerHttpReceiverData_V1,
+    SyncPeerHttpReceiverRel8ns_V1,
+    SyncPeerHttpReceiverIbGib_V1
+} from './sync-peer-http-receiver-types.mjs';
+import { putInSpace } from '../../../witness/space/space-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Http Receiver Peer implementation.
+ * Acts as the Symmetric Server Node. Accepts requests, routes to Receiver Coordinator.
+ */
+export class SyncPeerHttpReceiver_V1
+    extends SyncPeer_V1<InitializeSyncPeerHttpReceiverOpts>
+    implements SyncPeerHttpReceiverIbGib_V1 {
+
+    protected override lc: string = `[${SyncPeerHttpReceiver_V1.name}]`;
+
+    override get classname(): string {
+        return SyncPeerHttpReceiver_V1.name;
+    }
+
+    declare data: SyncPeerHttpReceiverData_V1 | undefined;
+    declare rel8ns: SyncPeerHttpReceiverRel8ns_V1 | undefined;
+
+    constructor(
+        initialData: SyncPeerHttpReceiverData_V1,
+        initialRel8ns?: SyncPeerHttpReceiverRel8ns_V1,
+    ) {
+        super(initialData, initialRel8ns);
+    }
+
+    protected async ensureLocalTempSpace(): Promise<IbGibSpaceAny> {
+        const lc = `${this.lc}[${this.ensureLocalTempSpace.name}]`;
+        try {
+            if (!this.opts) { throw new Error(`opts not initialized. (E: 3a77d1f466b92cc7940c0f241ac6c926)`); }
+
+            if (!this.opts.localTempSpace) {
+                const { localMetaspace } = this.opts;
+
+                const uuid = crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36);
+                const tempSpaceName = `tmp_sync_recv_${uuid.substring(0, 8)}`;
+                const localTempSpace = await localMetaspace.createNewLocalSpace({
+                    opts: {
+                        allowCancel: false,
+                        spaceName: tempSpaceName,
+                        getFnPrompt: localMetaspace.getFnPrompt!,
+                        logalot
+                    }
+                });
+                if (!localTempSpace) { throw new Error(`couldn't create a temp space (E: fed96e4491b7297240031fb7f04adf26)`); }
+                await localTempSpace.initialized;
+                this.opts.localTempSpace = localTempSpace;
+            }
+
+            return this.opts.localTempSpace;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    protected override async sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.sendContextRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 5297013216ae491894600b5a81115d26)`); }
+
+            // This method might not be directly called on the receiver in the same way
+            // as it is on the sender, or it handles the internal routing for the HTTP request.
+            // When an HTTP Endpoint receives a POST, it deserializes the context and triggers this.
+
+            throw new Error(`Not implemented (E: c56d5d6799b76bd8fd661846f6b9ee26)`);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Entry point from the HTTP Endpoint Adapter (e.g. Express POST route)
+     */
+    public async handleIncomingSyncRequest({
+        context,
+        controlIbGibs = [],
+    }: {
+        context: SyncSagaContextIbGib_V1;
+        controlIbGibs?: IbGib_V1[];
+    }): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.handleIncomingSyncRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 1de30d7db7e404ddf59eeed22a3bde26)`); }
+
+            if (!this.opts) { throw new Error(`opts not initialized. (E: 56f585e25a54489280c9ba1393a46226)`); }
+            const { localCoordinator, localMetaspace, localSpace } = this.opts;
+            const localTempSpace = await this.ensureLocalTempSpace();
+
+            // Put control ibgibs into durable space
+            const allControlIbGibs = [context, ...controlIbGibs];
+            for (const ibGib of allControlIbGibs) {
+                await putInSpace({ space: localSpace, ibGibs: [ibGib] });
+            }
+
+            // Put domain payloads into temp space
+            if (context.payloadIbGibsDomain && context.payloadIbGibsDomain.length > 0) {
+                for (const ibGib of context.payloadIbGibsDomain) {
+                    await putInSpace({ space: localTempSpace, ibGibs: [ibGib] });
+                }
+            }
+
+            const identitySecret = context.fnIdentitySecret ?
+                await context.fnIdentitySecret() :
+                undefined;
+
+            const responseCtx = await localCoordinator.continueSync({
+                sagaContext: context,
+                metaspace: localMetaspace,
+                mySpace: localSpace,
+                myTempSpace: localTempSpace,
+                identity: context.signedSessionKeystone,
+                identitySecret,
+            });
+
+            return responseCtx || undefined;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/sync/sync-peer/sync-peer-http-receiver/sync-peer-http-receiver-v1.mts.metadata.md

@@ -0,0 +1,71 @@
+# agent refactor metadata
+
+## guidelines
+
+* **Imports Order & logalot**:
+  * Imports should be organized in the following order:
+    1. non-@ibgib external dependencies
+    2. blank line
+    3. @ibgib external dependencies (order: helper-gib, ts-gib, encrypt-gib, core-gib, node-gib, web-gib)
+    4. blank line
+    5. `import { GLOBAL_LOG_A_LOT } from '../path/to/constants/file.mts';` (if applicable)
+    6. other local file imports
+    7. blank line
+    8. `const logalot = GLOBAL_LOG_A_LOT` (if applicable)
+    9. blank line
+  * So the `GLOBAL_LOG_A_LOT` is a local import, and this should be first iif the file contains any functions with logging.
+* **Tag Logging Messages with UUIDs**:
+  * Tag ALL logging messages, warnings, and errors with the proper prefix (e.g., I:, W:, E:) and a uuid inside parens, e.g., `(I: cfe7c7f220c84bd832bad493a9453826)`. Note: we will use `generate-id.js` for this.
+  * **Exception**: `console.error` logs inside a `catch` block should NOT have their own `(E: uuid)` since the thrown error or rejected promise should already contain it. Simply use `console.error(\`${lc} ${extractErrorMsg(error)}\`);`.
+
+## libs/core-gib/src/sync/sync-peer/sync-peer-http-receiver/sync-peer-http-receiver-v1.mts
+
+[changes will go here]
+
+### 2026/02/27 - 10:49 AM
+
+#### line 5 - Imports Order & logalot
+
+```typescript
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { SyncPeer_V1 } from '../sync-peer-v1.mjs';
+import { SyncSagaContextIbGib_V1 } from '../../sync-saga-context/sync-saga-context-types.mjs';
+import { IbGibSpaceAny } from '../../../witness/space/space-base-v1.mjs';
+import {
+    InitializeSyncPeerHttpReceiverOpts,
+    SyncPeerHttpReceiverData_V1,
+    SyncPeerHttpReceiverRel8ns_V1,
+    SyncPeerHttpReceiverIbGib_V1
+} from './sync-peer-http-receiver-types.mjs';
+import { putInSpace } from '../../../witness/space/space-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+```
+
+#### line 48+ - Tag Logging Messages with UUIDs
+
+```typescript
+    protected async ensureLocalTempSpace(): Promise<IbGibSpaceAny> {
+        // ...
+            if (!this.opts) { throw new Error(`opts not initialized. (E: 3a77d1f466b92cc7940c0f241ac6c926)`); }
+        // ...
+```
+
+```typescript
+    protected override async sendContextRequest(context: SyncSagaContextIbGib_V1): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.sendContextRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 5297013216ae491894600b5a81115d26)`); }
+            // ...
+```
+
+```typescript
+    public async handleIncomingSyncRequest({ ... }): Promise<SyncSagaContextIbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.handleIncomingSyncRequest.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 1de30d7db7e404ddf59eeed22a3bde26)`); }
+            // ...
+```

package/src/sync/sync-peer/sync-peer-http-sender/sync-peer-http-sender-types.mts

@@ -0,0 +1,32 @@
+/**
+ * @module sync-peer-http-sender-types
+ */
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { SyncPeerData_V1, SyncPeerRel8ns_V1, SyncPeerWitness, InitializeSyncPeerOpts } from '../sync-peer-types.mjs';
+
+/**
+ * Data for the SyncPeerHttpSender witness.
+ */
+export interface SyncPeerHttpSenderData_V1 extends SyncPeerData_V1 {
+    /** Http POST endpoint for sending context */
+    syncRoute: string;
+    /** Http GET endpoint for SSE events */
+    syncEventsRoute: string;
+}
+
+/**
+ * Relations for the SyncPeerHttpSender witness.
+ */
+export interface SyncPeerHttpSenderRel8ns_V1 extends SyncPeerRel8ns_V1 {
+}
+
+/**
+ * The SyncPeerHttpSender witness IbGib.
+ */
+export interface SyncPeerHttpSenderIbGib_V1 extends IbGib_V1<SyncPeerHttpSenderData_V1, SyncPeerHttpSenderRel8ns_V1> { }
+
+export interface InitializeSyncPeerHttpSenderOpts extends InitializeSyncPeerOpts {
+    /**
+     * Specific options needed for initializing the HTTP sender
+     */
+}