@ibgib/ts-gib 0.4.9 → 0.5.0

package/jasmine-browser.json

@@ -13,6 +13,6 @@
     "random": true
   },
   "browser": {
-    "name": "firefox"
+    "name": "headlessChrome"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/ts-gib",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "description": "ibgib library with low-level graphing-related substrate functionality, e.g. creating raw ibgibs and transformations. node19+ needed for heavily-used webcrypto hashing isomorphically consumed in node and browsers (apps).",
   "repository": {
     "url": "https://gitlab.com/ibgib/ts-gib",
@@ -32,6 +32,7 @@
     "test:browser:serve:nobuild": "npx jasmine-browser-runner serve --config=jasmine-browser.json ",
     "man:test:browser:serve:nobuild": "use this if you are troubleshooting existing dist output and don't want to overwrite those files. (and you're debugging in the browser)",
     "pack": "npm pack --pack-destination=\"./published\"",
+    "prepare:publish:minor": "npm run clean && npm version minor && npm run build && npm run pack",
     "prepare:publish": "npm run clean && npm version patch && npm run build && npm run pack",
     "man:prepare:publish": "use this to patch > build > pack for publishing to npm repo"
   },
@@ -57,5 +58,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@ibgib/helper-gib": "^0.0.2"
   }
 }

package/src/V1/constants.mts

@@ -1,8 +1,27 @@
 import { IbGib_V1 } from './types.mjs';
 
+/**
+ * This is essentially an alias of the string literal `'ib'`
+ */
 export const IB = 'ib';
+/**
+ * This is essentially an alias of the string literal `'gib'`
+ *
+ * When you have a primitive ibgib, this should be the `ibGib.gib` value, as
+ * there is no hashing metadata for primitives.
+ */
 export const GIB = 'gib';
+/**
+ * This is the root ibgib from which all ibgib are ultimately forked.
+ * It has 0 and infinite data, 0 and infinite rel8ns. Its ib and gib
+ * are simply 'ib' and 'gib'.
+ */
 export const ROOT: IbGib_V1 = { ib: IB, gib: GIB, }
+/**
+ * The default delimiter is the caret (^) symbol. This is derived from
+ * taking an ib^gib address and turning it into an ibGib object (note
+ * the capitalized "G").
+ */
 export const IBGIB_DELIMITER = '^';
 /**
  * Gib is often just a single hash for a single ib^gib record.
@@ -15,9 +34,18 @@ export const IBGIB_DELIMITER = '^';
  * @example "comment abc^TJPHASH123", "comment abc^TJPHASH123.THISRECORDHASH456"
  */
 export const GIB_DELIMITER = '.';
+/**
+ * This is the address of the ROOT ibgib with the default delimiter (caret ^).
+ */
 export const ROOT_ADDR = 'ib^gib'; // `${IB}${IBGIB_DELIMITER}${GIB}`;
-
 /**
- * Some rel8ns should not be able to be renamed or removed.
+ * Some rel8ns should not be able to be renamed or removed, as these have
+ * "special" semantic meaning in the low-level graphing protocol.
+ *
+ * ## notes
+ *
+ * * Of course, this can be forged or tinkered with, and that ultimately is what
+ *   consensus would be utilized for.
+ * * protocols built on top of this may also have reserved rel8n/data key names
  */
-export const FORBIDDEN_ADD_RENAME_REMOVE_REL8N_NAMES = ['past', 'ancestor', 'dna', 'tjp'];
+export const FORBIDDEN_ADD_RENAME_REMOVE_REL8N_NAMES = ['past', 'ancestor', 'dna', 'tjp'];

package/src/V1/factory.mts

@@ -9,6 +9,12 @@ export class Factory_V1 {
     static root() {
         return Factory_V1.primitive({ ib: IB });
     }
+
+    /**
+     * Returns an ibGib primitive with the given `ib`, e.g. "{ib: '7', gib: 'gib'}".
+     *
+     * @returns a single primitive ibGib
+     */
     static primitive({
         ib
     }: {
@@ -17,14 +23,24 @@ export class Factory_V1 {
         return { ib, gib: GIB };
     }
 
+    /**
+     * generates multiple primitive ibgibs from the given `ibs` array.
+     * @returns array of generated ibgibs.
+     */
     static primitives({
         ibs
     }: {
         ibs: Ib[]
-    }) {
+    }): IbGib_V1[] {
         return ibs.map(ib => Factory_V1.primitive({ ib }));
     }
 
+    /**
+     * Takes the incoming `parentIbGib` and forks it. Then applies the
+     * `data` and/or `rel8ns` if any, depending on the other config params.
+     *
+     * @returns The entire transform result object that includes the newly produced ibGib as well as any derivative/intermediate ibgibs.
+     */
     static async firstGen<TData = any>({
         ib = IB,
         parentIbGib = Factory_V1.root(),
@@ -45,7 +61,7 @@ export class Factory_V1 {
         linkedRel8ns?: string[],
         noTimestamp?: boolean,
         nCounter?: boolean,
-    }) {
+    }): Promise<TransformResult<IbGib_V1>> {
         const lc = `[firstGen]`;
         /** * Multiple transform steps will create multiple results. */
         const interimResults: TransformResult<IbGib_V1>[] = [];

package/src/V1/factory.spec.mts

@@ -2,7 +2,8 @@
 import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from './types.mjs';
 import { fork } from './transforms/fork.mjs';
 import { TransformOpts_Fork, IbGibAddr, Ib, TransformResult, IbGibRel8ns } from '../types.mjs';
-import { pretty, clone, delay, getIbGibAddr } from '../helper.mjs';
+import { getIbGibAddr, getIbAndGib } from '../helper.mjs';
+import { pretty, clone, delay, } from '@ibgib/helper-gib';
 import { ROOT, ROOT_ADDR } from './constants.mjs';
 import { Factory_V1 as factory } from './factory.mjs';
 import { mut8 } from './transforms/mut8.mjs';

package/src/V1/sha256v1.mts

@@ -1,9 +1,9 @@
-let crypto: any = globalThis.crypto;
-let { subtle } = crypto;
-
+import { extractErrorMsg } from "@ibgib/helper-gib";
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "./types.mjs";
 import { Ib } from "../types.mjs";
-import { extractErrorMsg } from "../helper.mjs";
+
+let crypto: any = globalThis.crypto;
+let { subtle } = crypto;
 
 /**
  * Performs the gib hash like V1
@@ -82,4 +82,4 @@ export async function hashToHexCopy(
         console.error(extractErrorMsg(e.message));
         return undefined;
     }
-};
+};

package/src/V1/transforms/fork.mts

@@ -1,4 +1,5 @@
-import { getIbGibAddr, clone, getUUID, getTimestamp } from '../../helper.mjs';
+import { getIbGibAddr } from '../../helper.mjs';
+import { clone, getUUID, getTimestamp } from '@ibgib/helper-gib';
 import { sha256v1 } from '../sha256v1.mjs';
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
 import { TransformOpts_Fork, TransformResult } from '../../types.mjs';

package/src/V1/transforms/fork.spec.mts

@@ -19,7 +19,8 @@
 import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
 import { fork } from './fork.mjs';
 import { TransformOpts_Fork, IbGibAddr, Ib, TransformResult } from '../../types.mjs';
-import { pretty, clone, delay, getIbGibAddr } from '../../helper.mjs';
+import { getIbGibAddr } from '../../helper.mjs';
+import { pretty, clone, delay, } from '@ibgib/helper-gib';
 import { ROOT, ROOT_ADDR } from '../constants.mjs';
 import { mut8 } from './mut8.mjs';
 import { getGib } from './transform-helper.mjs';

package/src/V1/transforms/mut8.mts

@@ -1,4 +1,5 @@
-import { getIbGibAddr, clone, getTimestamp } from '../../helper.mjs';
+import { getIbGibAddr } from '../../helper.mjs';
+import { clone, getTimestamp, } from '@ibgib/helper-gib';
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
 import { TransformOpts_Mut8, TransformResult } from '../../types.mjs';
 import { IBGIB_DELIMITER, } from '../constants.mjs';

package/src/V1/transforms/mut8.spec.mts

@@ -7,11 +7,12 @@
  *   going.
  */
 
-import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
+import { IbGib_V1, IbGibRel8ns_V1 } from '../types.mjs';
 import { TransformOpts_Mut8, IbGibAddr } from '../../types.mjs';
-import { pretty, clone, delay, getIbGibAddr, getIbAndGib, } from '../../helper.mjs';
+import { getIbGibAddr, getIbAndGib, } from '../../helper.mjs';
+import { clone, delay, } from '@ibgib/helper-gib';
 import { sha256v1, } from '../sha256v1.mjs';
-import { ROOT, ROOT_ADDR, GIB_DELIMITER } from '../constants.mjs';
+import { ROOT } from '../constants.mjs';
 import { fork } from './fork.mjs';
 import { mut8 } from './mut8.mjs';
 import { Factory_V1 as factory } from '../factory.mjs';

package/src/V1/transforms/rel8.mts

@@ -1,4 +1,5 @@
-import { getIbGibAddr, clone, getTimestamp } from '../../helper.mjs';
+import { getIbGibAddr, getIbAndGib } from '../../helper.mjs';
+import { pretty, clone, delay, getTimestamp, } from '@ibgib/helper-gib';
 import { sha256v1 } from '../sha256v1.mjs';
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
 import { TransformOpts_Rel8, TransformResult, IbGibAddr } from '../../types.mjs';

package/src/V1/transforms/rel8.spec.mts

@@ -9,7 +9,8 @@
 
 import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
 import { TransformOpts_Rel8, IbGibAddr, IbGibRel8ns } from '../../types.mjs';
-import { pretty, clone, delay, getIbGibAddr, getIbAndGib } from '../../helper.mjs';
+import { getIbGibAddr, getIbAndGib } from '../../helper.mjs';
+import { pretty, clone, delay, } from '@ibgib/helper-gib';
 import { ROOT, ROOT_ADDR } from '../constants.mjs';
 import { fork } from './fork.mjs';
 // import { mut8 } from './mut8.mjs';

package/src/V1/transforms/transform-helper.mts

@@ -1,5 +1,6 @@
-import { TransformOpts, IbGib, Gib, Ib, IbGibAddr, } from "../../types.mjs";
-import { clone, getIbGibAddr, getIbAndGib, HashAlgorithm, extractErrorMsg, } from "../../helper.mjs";
+import { clone, extractErrorMsg, } from "@ibgib/helper-gib";
+import { TransformOpts, IbGib, Gib, IbGibAddr, } from "../../types.mjs";
+import { getIbGibAddr, getIbAndGib, } from "../../helper.mjs";
 import { sha256v1, } from "../sha256v1.mjs";
 import { GibInfo, IbGib_V1, } from "../types.mjs";
 import { IBGIB_DELIMITER, GIB, GIB_DELIMITER } from "../constants.mjs";

package/src/V1/transforms/transform-helper.spec.mts

@@ -3,13 +3,14 @@
  */
 
 
-import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
-import { TransformOpts_Rel8, IbGibAddr, IbGibRel8ns } from '../../types.mjs';
-import { pretty, clone, delay, getIbGibAddr } from '../../helper.mjs';
-import { ROOT, ROOT_ADDR } from '../constants.mjs';
+// import { IbGib_V1, IbGibRel8ns_V1, Rel8n } from '../types.mjs';
+// import { TransformOpts_Rel8, IbGibAddr, IbGibRel8ns } from '../../types.mjs';
+// import { getIbGibAddr, getIbAndGib } from '../../helper.mjs';
+// import { pretty, clone, delay, } from '@ibgib/helper-gib';
+// import { ROOT, ROOT_ADDR } from '../constants.mjs';
 import { fork } from './fork.mjs';
 // import { mut8 } from './mut8.mjs';
-import { rel8 } from './rel8.mjs';
+// import { rel8 } from './rel8.mjs';
 import { Factory_V1 as factory } from '../factory.mjs';
 import { isDna } from './transform-helper.mjs';
 

package/src/V1/v1-helper.mts

@@ -0,0 +1,90 @@
+import { getIbGibAddr, getIbAndGib } from '../helper.mjs';
+import { pretty, clone, delay, } from '@ibgib/helper-gib';
+import * as cTsGib from './constants.mjs';
+import { getGibInfo } from './transforms/transform-helper.mjs';
+import { IbGibRel8ns_V1, IbGib_V1 } from "./types.mjs";
+
+/**
+ * Helper function that checks the given `ibGib` to see if it
+ * either has a tjp or is a tjp itself.
+ *
+ * ## notes
+ *
+ * Only unique ibGibs are meant to have tjps, or rather, if an
+ * ibGib timeline is expected to be unique over "time", then the
+ * tjp is an extremely convenient mechanism that provides a
+ * "name" for that timeline.
+ *
+ * Otherwise, if they are not unique, then successive "different"
+ * timelines cannot be easily referenced by their first unique
+ * frame in time, making it much harder to pub/sub updates among
+ * other things. (If there are no unique frames, then they are
+ * the same ibGib.)
+ *
+ * ## tjp = temporal junction point
+ *
+ * I've written elsewhere on this as well. Refer to B2tF2.
+ *
+ * @returns true if the ibGib has/is a tjp, else false
+ */
+export function hasTjp({ ibGib }: { ibGib: IbGib_V1 }): boolean {
+    const lc = `[${hasTjp.name}]`;
+
+    if (!ibGib) {
+        console.warn(`${lc} ibGib falsy. (W: 884178562f5b4f15933ac4d98db74cc6)`);
+        return false;
+    }
+
+    if (ibGib.data?.isTjp || ibGib.rel8ns?.tjp?.length! > 0) {
+        return true;
+    }
+
+    // dna transforms do not have tjp
+    const dnaPrimitives = ['fork^gib', 'mut8^gib', 'rel8^gib'];
+    if ((ibGib.rel8ns?.ancestor ?? []).some(x => dnaPrimitives.includes(x))) {
+        return false;
+    }
+
+    if (!ibGib.gib) {
+        console.warn(`${lc} ibGib.gib falsy. (W: 6400d780822b44d992846f1196509be3)`);
+        return false;
+    }
+    if (ibGib.gib.includes(cTsGib.GIB_DELIMITER)) {
+        return true;
+    }
+
+    if (ibGib.gib === cTsGib.GIB) {
+        // primitive
+        return false;
+    }
+
+    // use more expensive getGibInfo call.
+    // could possibly just return false at this point, but since gib info
+    // would change if we change our standards for gib, this is nicer.
+    const gibInfo = getGibInfo({ ibGibAddr: getIbGibAddr({ ibGib }) });
+    return gibInfo.tjpGib ? true : false;
+}
+
+/**
+ * If you have an ibgib object, it may also contain other properties/functions.
+ *
+ * This helper function takes the incoming object and returns a copy
+ * @param param0
+ * @returns
+ */
+export function toDto<TData, TRel8ns extends IbGibRel8ns_V1 = IbGibRel8ns_V1>({
+    ibGib,
+}: {
+    ibGib: IbGib_V1,
+}): IbGib_V1<TData, TRel8ns> {
+    const lc = `[${toDto.name}]`;
+    if (!ibGib.ib) { console.warn(`${lc} ibGib.ib is falsy. (W: e60e41c2a1fc48268379d88ce13cb77b)`); }
+    if (!ibGib.gib) { console.warn(`${lc} ibGib.gib is falsy. (W: fb3889cbf0684ae4ac51e48f28570377)`); }
+
+    let dtoIbGib: IbGib_V1<TData, TRel8ns> = { ib: (ibGib.ib || '').slice() };
+    if (ibGib.gib) { dtoIbGib.gib = ibGib.gib.slice(); };
+    if (ibGib.data) { dtoIbGib.data = clone(ibGib.data); }
+    if (ibGib.rel8ns) { dtoIbGib.rel8ns = clone(ibGib.rel8ns); }
+
+    return dtoIbGib;
+}

package/src/V1/validate-helper.mts

@@ -0,0 +1,286 @@
+import { Ib, IbGibAddr, } from '../types.mjs';
+import { IbGib_V1, } from './types.mjs';
+import { IBGIB_DELIMITER, GIB, IB, GIB_DELIMITER, } from './constants.mjs';
+import { isPrimitive, getGib, getGibInfo } from './transforms/transform-helper.mjs';
+
+// import { hasTjp, toDto } from './ibgib';
+
+import { hasTjp, toDto } from './v1-helper.mjs';
+import { HEXADECIMAL_HASH_STRING_REGEXP_32, HEXADECIMAL_HASH_STRING_REGEXP_64 } from '@ibgib/helper-gib';
+import { getIbAndGib, getIbGibAddr } from '../helper.mjs';
+
+const logalot = false;
+
+/**
+ * validates the ibGib's address (`ib` and `gib` properties) and recalculates
+ * the `gib` against the `ibGib.gib`.
+ *
+ * this validates not only that the punctiliar gib hash for this ibgib record
+ * hashes to the same value, but it also checks the internal tjp address and
+ * ensures that it is the same tjp gib in the gib field.
+ *
+ * ## notes
+ *
+ * * By checking the tjp gib is the same in the address as in the tjp rel8n, we
+ *   are providing (extremely?) good corroboration that the tjp listed in the
+ *   address is accurate. However, it may still be theoretically possible to
+ *   forge an ibgib that both hashes to the punctiliar hash and matches up this
+ *   tjpAddr.gib. This would be AFAICT quite challenging.
+ */
+export async function validateIbGibIntrinsically({
+    ibGib
+}: {
+    ibGib: IbGib_V1
+}): Promise<string[] | null> {
+    const lc = `[${validateIbGibIntrinsically.name}]`;
+    try {
+        let errors: string[] = [];
+        if (ibGib) {
+            const addr = getIbGibAddr({ ibGib });
+            errors = validateIbGibAddr({ addr }) ?? [];
+
+            if (errors.length > 0) {
+                console.error(`${lc} errors found in addr: ${addr}`);
+                return errors; // <<<< returns early
+            }
+
+            // rest of the function assumes correctly formatted ib and gib
+
+            // if it's a primitive, the caller knows (or should know!) there are no
+            // metadata guarantees.
+            if (isPrimitive({ gib: ibGib.gib })) { return null; }
+
+            // this validates not only that the punctiliar gib hash for this ibgib record
+            // hashes to the same value, but it also checks the internal tjp address and
+            // ensures that it is the same tjp gib.
+            // not necessary the dto here, but I'm sensitive at this point.
+            let gottenGib = await getGib({ ibGib: toDto({ ibGib }), hasTjp: hasTjp({ ibGib }) });
+            if (gottenGib !== ibGib.gib) {
+                if (ibGib.data?.src && ibGib.data.srcAddr && ibGib.ib === 'rel8') {
+                    // this is NOT the place to do this, but I'm plodding through trying to think of how to fix it
+                    // this is what it looks like in data
+                    // {
+                    //     "rel8nsToAddByAddr":{
+                    //         "comment":["comment 11221^F6B9477984D31FEF5FD25297CA39126A64ADDE2C91C1A2D670CCFE3965DEC4C9.847F0E9A1B2738DC167B32AA9B2D7D9B88B76F21848B1F193E994BB21F90DAEE"]
+                    //     },
+                    //     "dna":true,
+                    //     "nCounter":true,
+                    //     "type":"rel8"
+                    // }
+                    delete ibGib.data.src;
+                    delete ibGib.data.srcAddr;
+                    gottenGib = await getGib({ ibGib: toDto({ ibGib }), hasTjp: hasTjp({ ibGib }) });
+                    if (gottenGib !== ibGib.gib) {
+                        errors.push(`Ibgib invalid intrinsically - gottenGib (${gottenGib}) does not equal ibGib.gib (${ibGib.gib}). (E: 020b71479e944b2198fe436e7e137786)`);
+                        // } else {
+                        //     debugger;
+                    }
+                } else {
+                    errors.push(`Ibgib invalid intrinsically - gottenGib (${gottenGib}) does not equal ibGib.gib (${ibGib.gib}). (E: 7416db016878430ca3c5b20697f164ed)`);
+                }
+            }
+
+            return errors.length > 0 ? errors : null;
+        } else {
+            errors.push(`ibGib is itself falsy. (E: 4fb98caf6ed24ef7b35a19cef56e2d7e)`);
+            return errors;
+        }
+
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    }
+}
+
+/**
+ * Naive synchronous validation for ibgib addresses.
+ *
+ * @returns error string array if validation errors found, else null
+ */
+export function validateIbGibAddr({
+    addr,
+    delimiter,
+    version,
+}: {
+    addr: IbGibAddr,
+    delimiter?: string,
+    version?: string,
+}): string[] | null {
+    const lc = `[${validateIbGibAddr.name}]`;
+    try {
+        let errors: string[] = [];
+        if (version) { console.warn(`${lc} version not implemented yet. Ignoring. (W: 2d19db16ec0c4766b5d35248787671f3)`); }
+
+        // validate as a whole
+        if (!addr) {
+            errors.push(`addr required. (E: e9a54041aa0b41c1bb2324d9d2d42c7f)`);
+            return errors;
+        }
+        delimiter = delimiter || IBGIB_DELIMITER;
+        if (!addr.includes(delimiter)) { errors.push(`No delimiter (${delimiter}) found. (E: 05e28dcb70ff44019edc53ed508bd1e8)`); }
+        if (addr.startsWith(delimiter)) { errors.push(`addr starts with delim. (E: d29f808c5a47452f9bb3ea684694c6eb)`); }
+
+        // validate pieces...
+        const { ib, gib } = getIbAndGib({ ibGibAddr: addr, delimiter });
+
+        // ...ib
+        const resValidateIb = validateIb({ ib, ibGibAddrDelimiter: delimiter, version });
+        if (resValidateIb) { errors = errors.concat(resValidateIb); }
+
+        // ...gib
+        const resValidateGib = validateGib({ gib, ibGibAddrDelimiter: delimiter, version });
+        if (resValidateGib) { errors = errors.concat(resValidateGib); }
+
+        if (errors.length > 0) {
+            if (logalot) { console.log(`${lc} errors.length > 0. errors: ${errors.join('|')} (I: 9c18f993e138f15613e4c6a340d41722)`); }
+        }
+
+        // we're done
+        return errors.length > 0 ? errors : null;
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    }
+}
+
+/**
+ * Naive validation of ib.
+ *
+ * @returns errors array if found, else null
+ */
+export function validateIb({
+    ib,
+    ibGibAddrDelimiter,
+    version,
+}: {
+    ib: Ib,
+    ibGibAddrDelimiter?: string,
+    version?: string,
+}): string[] | null {
+    const lc = `[${validateIb.name}]`;
+    try {
+        const errors: string[] = [];
+        if (version) { console.warn(`${lc} version not implemented yet. Ignoring. (W: 71228ba4ed994aaa8149910e295ab087)`); }
+
+        if (!ib) {
+            errors.push(`ib required. (E: a76d06c7b9c24db3a731a91dbe46acd5)`);
+            return errors;
+        }
+
+        if (ib === IB) { return null; }
+
+        ibGibAddrDelimiter = ibGibAddrDelimiter || IBGIB_DELIMITER;
+        if (ib.includes(ibGibAddrDelimiter)) { errors.push(`ib contains ibGibAddrDelimiter (${ibGibAddrDelimiter}) (E: 09e61b46c3e84874bc02b6918f1f2c39)`); }
+
+        return errors.length > 0 ? errors : null;
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    }
+}
+
+/**
+ * validates a `gib` of some ibGib/ibGibAddr.
+ *
+ * @returns array of validation error strings (if any) or null
+ */
+export function validateGib({
+    gib,
+    gibDelimiter,
+    ibGibAddrDelimiter,
+    version,
+}: {
+    /**
+     * gib to validate.
+     *
+     * ## notes
+     *
+     * If the gib has a tjp embedded in it (i.e. the associated ibgib has a
+     * tjp), then this will call validation on that tjpGib recursively.
+     */
+    gib: Ib,
+    /**
+     * This is a delimiter used with tjpGibs.
+     *
+     * atow this is a dot (`'.'`).
+     *
+     * ## notes
+     *
+     * THIS IS NOT THE SAME THING AS THE `ibGibAddrDelimiter`!
+     */
+    gibDelimiter?: string,
+    /**
+     * This is a delimiter used with the entire ibGibAddr.
+     *
+     * atow this is a caret (`'^'`).
+     *
+     * ## notes
+     *
+     * THIS IS NOT THE SAME THING AS THE `gibDelimiter`!
+     */
+    ibGibAddrDelimiter?: string,
+    /**
+     * Ignored atow, but in the future, probably will be used.
+     * May end up being an IbGibAddr but who knows.
+     */
+    version?: string,
+}): string[] | null {
+    const lc = `[${validateGib.name}]`;
+    try {
+        const errors: string[] = [];
+        if (version) { console.warn(`${lc} version not implemented yet. Ignoring. (E: 90ced1db69774702b92acb261bdaee23)`); }
+
+        if (!gib) {
+            errors.push(`gib required. (E: e217de4035b04086827199f4bace189c)`);
+            return errors;
+        }
+
+        ibGibAddrDelimiter = ibGibAddrDelimiter || IBGIB_DELIMITER;
+        /** Need to move this to ts-gib */
+        const INVALID_GIB_CHARS = [ibGibAddrDelimiter];
+        const invalidCharsFound: string[] = [];
+        INVALID_GIB_CHARS.forEach(invalidChar => {
+            if (gib.includes(invalidChar)) { invalidCharsFound.push(invalidChar); }
+        });
+        if (invalidCharsFound.length > 0) {
+            errors.push(`gib (${gib}}) contains invalid characters: (${JSON.stringify(invalidCharsFound.join(','))}) (E: 1e584258d9e049ba9ce7e516f3ab97f1)`);
+        }
+
+        // punctiliar = point, i.e., a single point in the universe, either a
+        // single point in time in a tjp ibgib's timeline, or a single point in
+        // space that lives outside of time (has no tjp thus no timeline).
+        //
+        // So if we've gotten here in code, then our gib is truthy and doesn't
+        // contain invalid characters.
+
+        const { punctiliarHash, tjpGib, isPrimitive } =
+            getGibInfo({ gib, gibDelimiter: gibDelimiter || GIB_DELIMITER });
+
+        // automatically valid if it's a primitive, as the caller should expect
+        // no cryptographical guarantees
+        if (isPrimitive) { return null; }
+
+        // Gib is not primitive so must have at least the punctiliar hash.
+        if (!punctiliarHash) { throw new Error(`${lc} punctiliarHash is falsy on a non-primitive gib. (E: 72835394918241bdb2632bf0510bdae5)`); }
+        const punctiliarHashIs_32 = punctiliarHash!.match(HEXADECIMAL_HASH_STRING_REGEXP_32);
+        const punctiliarHashIs_64 = punctiliarHash!.match(HEXADECIMAL_HASH_STRING_REGEXP_64);
+        if (!punctiliarHashIs_32 && !punctiliarHashIs_64) {
+            errors.push('gib punctiliar hash is neither a 32- or 64-char hash string. (E: d47ff6d6e14b4c02a62107090c8dad39)');
+        }
+
+        if (tjpGib) {
+            // if it is an ibgib in a timeline, that timeline has a tjp and this
+            // gib has a tjpGib component. So we must recursively validate the
+            // tjpGib
+            const tjpGibValidationErrors = validateGib({ gib: tjpGib });
+            if ((tjpGibValidationErrors ?? []).length > 0) {
+                errors.push(`tjpGib has errors (E: d6b79228d4a64c0b967cdb0efcea4d0d). tjpGibValidationErrors: ${tjpGibValidationErrors!.join('. ')}`);
+            }
+        }
+
+        return errors.length > 0 ? errors : null;
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    }
+}