@ibgib/node-gib 0.0.2

package/src/witness/space/metaspace/metaspace-nodespace/metaspace-nodespace.mts

@@ -0,0 +1,166 @@
+/**
+ * @module node-metaspace driven by a node+fs storage substrate
+ *
+ * a metaspace is a space of spaces. it adds/removes spaces and does
+ * inter-spatial composition related things. it's similar to what people think
+ * of in terms of a node in a p2p network.
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { IbGibCacheService } from '@ibgib/core-gib/dist/common/cache/cache-types.mjs';
+import { MetaspaceBase } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-base.mjs';
+import { MetaspaceFactory } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+
+import { GLOBAL_LOG_A_LOT, GLOBAL_TIMER_NAME } from '../../../../constants.mjs';
+import { fnCreateNewLocalSpace, fnDtoToSpace_nodeFilesystem } from './metaspace-nodespace-helper.mjs';
+import { NodeFilesystemSpace_V1 } from '../../node-filesystem-space/node-filesystem-space-v1.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * All-purpose mega service (todo: which we'll need to break up!) to interact
+ * with ibgibs at the app/device level.
+ *
+ * This works with the local app user space.
+ *
+ * ## regarding special ibgibs
+ *
+ * Special ibgibs' behaviors are what hold in other apps configuration data.
+ * Of course the difference is that most special ibgibs can leverage the "on-chain"
+ * functionality of "regular" ibgibs.
+ *
+ * There are a couple meta ibgibs (which I also call "special"):
+ *   * roots^gib
+ *     * tracks other special root^gib ibgibs, which are like local app-level indexes.
+ *   * tags^gib
+ *     * tracks other special tag^gib ibgibs, which you can apply to any ibgib
+ *   * latest^gib
+ *     * tracks mappings between tjp -> latest ib^gib address
+ *     * ephemeral (deletes past rel8ns and past ibGib frames)
+ *   * ...
+ *
+ * ## regarding latest ibgibs
+ *
+ * The tjp (temporal junction point) defines atow the beginning of an ibGib
+ * timeline.  it's like the birthday for an ibGib. (Or you can think if it as
+ * the id for the stream of ibgib frames in a given timeline.)
+ *
+ * The latest ibGib in that timeline is also special, because it's often what
+ * you want to work with.
+ *
+ * So ideally, when an ibgib, A, has a tjp A1, and it is updated to A2, A3, An
+ * via `mut8` and/or `rel8` transforms, that ibgib creates a single timeline.
+ * This service attempts to track the relationship between that starting tjp
+ * address and its corresponding latest frame in that timeline, i.e., A1 -> An.
+ *
+ * ### mapping persistence implementation details
+ *
+ * The latest ibGib service is backed by a special ibgib that maintains the
+ * mapping index.  It does this by rel8-ing that special backing ibgib via the
+ * tjp pointer, e.g. [special latest ibgib^XXX000].rel8ns[A^TJP123] ===
+ * [A^N12345] . It does this via the ib^gib content address pointer, so this
+ * becomes a mapping from A^TJP123 to A^N12345.
+ *
+ * This backing ibGib is special (even for special ibGibs) in that:
+ *   * it does not relate itself with the current root of the application
+ *   * it does not maintain references to its past (i.e. rel8ns['past'] === [])
+ *   * it DELETES its previous incarnation from the files service
+ *
+ * In other words, this service is meant to be as ephemeral as possible. I am
+ * keeping it as an ibGib and not some other data format (like straight in
+ * storage/some other db) because I've found this is often useful and what I end
+ * up doing anyway to leverage other ibgib behavior. For example, in the future
+ * it may be good to take snapshots, which is a simple copy operation of the
+ * file persistence.
+ *
+ * ### current naive implementation notes
+ *
+ * questions:
+ *   * What do we want to do if we can't locate an ibGib record?
+ *   * How/when do we want to alert the user/our own code that we've found
+ *     multiple timelines for an ibGib with a tjp (usually a thing we want to
+ *     avoid)?
+ *   * Who do we want to notify when new ibGibs arrive?
+ *   * How often do we want to check external sources for latest?
+ *   * When do we get to merging ibGib timelines?
+ *
+ * This is behavior that is somewhat taken care of, e.g. in git, with the HEAD
+ * pointer for a repo.  But we're talking about here basically as a metarepo or
+ * "repo of repos", and unlike git, we don't want our HEAD metadata living "off
+ * chain" (outside of the DLT itself that it's modifying).  So eventually, what
+ * we want is just like what we want with ALL ibGibs: perspective. From "the
+ * app"'s perspective, the latest is mapped. But really, apps can't view slices
+ * of ibGib graphs in all sorts of interesting ways and still be productive &
+ * beneficial to the ecosystem as a whole.
+ */
+export class Metaspace_Nodespace extends MetaspaceBase {
+
+  // we won't get an object back, only a DTO ibGib essentially
+  protected lc: string = `[${Metaspace_Nodespace.name}]`;
+
+  get zeroSpace(): IbGibSpaceAny {
+    const lc = `[${this.lc}][get zeroSpace]`;
+    if (this.metaspaceFactory.fnZeroSpaceFactory) {
+      return this.metaspaceFactory.fnZeroSpaceFactory();
+    } else {
+      throw new Error(`${lc} (UNEXPECTED) this.metaspaceFactory.fnZeroSpaceFactory falsy. not initialized? (E: 9e6c6954dacd868b18c9f34a71e63523)`);
+    }
+  }
+
+  constructor(
+    // public modalController: ModalController,
+    // public alertController: AlertController,
+    protected cacheSvc: IbGibCacheService | undefined,
+    // private latestCacheSvc: IonicStorageLatestIbgibCacheService,
+  ) {
+    super(cacheSvc);
+    const lc = `${this.lc}[ctor]`;
+    if (logalot) {
+      console.log(`${lc}${GLOBAL_TIMER_NAME}`);
+      console.timeLog(GLOBAL_TIMER_NAME);
+      console.log(`${lc} created. (I: 5690dc2ebf774df3a442bd463dee7455)`);
+    }
+
+  }
+
+  protected async initializeMetaspaceFactory({ metaspaceFactory }: {
+    metaspaceFactory: MetaspaceFactory,
+  }): Promise<void> {
+    const lc = `[${this.initializeMetaspaceFactory.name}]`;
+    try {
+      if (logalot) { console.log(`${lc} starting... (I: 5a29670439ac47634dcdfe25225c8223)`); }
+
+      await super.initializeMetaspaceFactory({ metaspaceFactory });
+
+      metaspaceFactory.fnDefaultLocalSpaceFactory ??= (opts) => fnCreateNewLocalSpace(opts);
+      metaspaceFactory.fnDtoToSpace ??= (spaceDto) => fnDtoToSpace_nodeFilesystem(spaceDto);
+
+      this.metaspaceFactory.fnZeroSpaceFactory ??= () => {
+        // default to node space
+        const zeroSpace = new NodeFilesystemSpace_V1(/*initialData*/ undefined, /*initialRel8ns*/ undefined);
+        zeroSpace.gib = 'gib';
+        return zeroSpace;
+      }
+    } catch (error) {
+      console.error(`${lc} ${extractErrorMsg(error)}`);
+      throw error;
+    } finally {
+      if (logalot) { console.log(`${lc} complete.`); }
+    }
+  }
+
+  async initializeZeroSpace(): Promise<void> {
+    const lc = `[${this.initializeZeroSpace.name}]`;
+    try {
+      if (logalot) { console.log(`${lc} starting... (I: a3364e9601c70c8163e67868e5d67723)`); }
+
+    } catch (error) {
+      console.error(`${lc} ${extractErrorMsg(error)}`);
+      throw error;
+    } finally {
+      if (logalot) { console.log(`${lc} complete.`); }
+    }
+  }
+
+}

package/src/witness/space/node-filesystem-space/node-filesystem-space-helper.mts

@@ -0,0 +1,298 @@
+/**
+ * @module node-filesystem-space-helper
+ *
+ */
+
+
+import { readFile, } from 'node:fs/promises';
+import { default as pathUtils } from 'path';
+import { cwd } from 'node:process';
+
+import { extractErrorMsg, unique, } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { getIbAndGib, } from '@ibgib/ts-gib/dist/helper.mjs';
+import { GIB, } from '@ibgib/ts-gib/dist/V1/index.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '@ibgib/core-gib/dist/core-constants.mjs';
+import { parseSpaceIb, } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { NodeFilesystemSpace_V1 } from './node-filesystem-space-v1.mjs';
+import { B2TFS_DEFAULT_ENCODINGS_TO_TRY, FILE_ENCODINGS, FileDataInfo, FileEncoding } from './node-filesystem-space-types.mjs';
+
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * tries to read the given path. if fails **FOR ANY REASON**, @returns `null`.
+ *
+ * does not throw
+ *
+ * @returns file contents as string or `null`
+ */
+export async function tryRead({
+    path,
+    directory,
+    encoding,
+}: {
+    path: string,
+    directory: string,
+    encoding: string,
+}): Promise<string | Uint8Array | null> {
+    const lc = `[${tryRead.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting...`);
+            console.log(`${lc} cwd: ${cwd()}`);
+            if (path.includes('bootstrap^gib')) { console.log(`${lc} trying bootstrap^gib... (I: dacfdbe5a2d640ab947a7c17e3c56f78)`); }
+        }
+        const fullPath = pathUtils.join(directory, path);
+        if (logalot) { console.log(`${lc} fullPath: ${fullPath} (I: 459b416ac32c711bfbab54177839b323)`); }
+        encoding ||= 'utf8';
+        let resRead: string | undefined = undefined;
+        resRead = await readFile(fullPath, { encoding: encoding as BufferEncoding });
+
+        if (logalot) {
+            console.log(`${lc} record found. data length: ${resRead?.length ?? 0}. fullPath: ${fullPath}. console.dir(resRead)... (I: 82e3ad9821bd4bf8a54c8facc61dbad0)`);
+            console.dir(resRead)
+        }
+        return resRead;
+    } catch (error) {
+        if (logalot) {
+            console.log(`${lc} fullPath not found from directory (${directory}) and path (${path})\nerror:\n${extractErrorMsg(error)} (I: 1fde689d29aa47fcb589b3e7dac8929b)`);
+        }
+        return null;
+    } finally {
+        if (logalot) { console.log(`${lc} complete. (I: e2615c944a464cd48a5635fe401562d9)`); }
+    }
+}
+
+export async function tryRead_bin({
+    path,
+    directory,
+    encoding,
+}: {
+    path: string,
+    directory: string,
+    encoding: string,
+}): Promise<FileDataInfo | null> {
+    const lc = `[${tryRead_bin.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting...`);
+            console.log(`${lc} cwd: ${cwd()}`);
+            if (path.includes('bootstrap^gib')) { console.log(`${lc} trying bootstrap^gib... (I: 5eb010444b814addb1a6bbe18ca3dbfa)`); }
+        }
+        const fullPath = pathUtils.join(directory, path);
+        if (logalot) { console.log(`${lc} fullPath: ${fullPath} (I: c342bf56df354e9ab2653855a458b99d)`); }
+        encoding ||= 'utf8';
+        let resRead: string | Uint8Array | undefined = undefined;
+        let encodingsToTry: FileEncoding[] = unique<FileEncoding>([
+            encoding as FileEncoding,
+            ...FILE_ENCODINGS,
+        ]);
+        let { dataBuffer, dataString, inputPath, detectedEncoding } = await getFileDataAndEncoding({
+            inputPath: path,
+            encodingsToTry,
+        });
+        if (!dataBuffer) { throw new Error(`getFileDataAndEncoding yielded falsy dataBuffer (E: f7aac299212a1ae41d5bbef6079c4d24)`); }
+        resRead = dataBuffer;
+
+        if (logalot) {
+            console.log(`${lc} record found. data length: ${resRead?.length ?? 0}. fullPath: ${fullPath}. console.dir(resRead)... (I: 438189ba2fd345d782f928ecc7dc6e58)`);
+            console.dir(resRead)
+        }
+
+        return {
+            dataBuffer, dataString, inputPath, detectedEncoding
+        };
+    } catch (error) {
+        if (logalot) {
+            console.log(`${lc} fullPath not found from directory (${directory}) and path (${path})\nerror:\n${extractErrorMsg(error)} (I: 882e54f079024c94864bdaa74979b397)`);
+        }
+        return null;
+    } finally {
+        if (logalot) { console.log(`${lc} complete. (I: 500e391835aa4d959adf4720fdc38c4b)`); }
+    }
+}
+
+/**
+ * basic validation for a node fs space ibgib
+ */
+export async function validateNodeFilesystemSpace_V1Intrinsically({ space }: { space: NodeFilesystemSpace_V1<any, any> }): Promise<string[] | null> {
+    const lc = `[${validateNodeFilesystemSpace_V1Intrinsically.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: fcfe57145426ab4a5a0e961e87001922)`); }
+        const errors: string[] = (await validateIbGibIntrinsically({ ibGib: space })) ?? [];
+
+        const { ib, gib, data, rel8ns } = space;
+
+        if (!ib) { errors.push('ib required. (E: e69ddadd947d4534ae60af9eda1bda47)'); }
+        if (!gib) { errors.push('gib required. (E: 9794fb92dd79473b9139c001f0634ec2)'); }
+        if (gib === GIB) { errors.push('gib cannot be primitive. (E: 651c12f1303d45aba54aa228eca1e575)'); }
+
+        if (!data) {
+            errors.push('data required. (E: 264d13ce6b47400e8943bf046c57e8bc)');
+            return errors;
+        }
+
+        if (!data.name) { errors.push('space name required. (E: 4845041c9f2e44098e1e7bb30fe3c13d)') }
+        // if (!data.classname) { errors.push('classname required. (E: cb645bebf8fc4baabfbf74be39563008)') }
+        if (data.classname && data.classname !== NodeFilesystemSpace_V1.name) {
+            errors.push(`unknown classname (${data.classname}). data.classname !== FilesystemSpace_V1.name (E: e159eb46ca5e4c2b850998af88cb5840)`);
+        }
+        if (!data.baseDir) { errors.push(`data.baseDir required (E: 373544741a974ab9bc0001d3d63c2601).`) }
+        if (!data.baseSubPath) { errors.push(`data.baseSubPath required. (E: 7336f8eb7c7846d48993e0db893fb7cb)`) }
+        if (!data.binSubPath) { errors.push(`data.binSubPath required. (E: 3544a80a3cec4fdfb35d3e6ccb36dbd6)`) }
+        if (!data.dnaSubPath) { errors.push(`data.dnaSubPath required. (E: 4d6e529cdd0f47a492545c31e1dda865)`) }
+        if (!data.ibgibsSubPath) { errors.push(`data.ibgibsSubPath required. (E: 11b90fdc1b1c41b492c26a61da3409b8)`) }
+        if (!data.metaSubPath) { errors.push(`data.metaSubPath required. (E: 259113f4f0bc488785f9019160c8a226)`) }
+        if (data.n && typeof data.n !== 'number') { errors.push(`data.n must be a number. (E: e7c76f44b1114dba949d06146a8c169b)`) }
+        if (data.n === undefined) {
+            // the very first space record (tjp) has an undefined n and no rel8ns
+            if (rel8ns) { errors.push(`rel8ns not expected when data.n is falsy (custom temporal junction point indicator I suppose...) (E: 08604c8b33524009886ac2c63eb34c50)`); }
+        }
+        if (!data.spaceSubPath) { errors.push(`data.spaceSubPath required. (E: 1688a59dfc6447b3bccb7690b233e4fa)`) }
+        if (!data.uuid) { errors.push(`data.uuid required. (E: dd984a04d0d14d16a4faa300ec125960)`) }
+        if (!data.encoding) { errors.push(`data.encoding required. (E: e75958932f614364a1765a875acad2ce)`) }
+        /** should probably get this from Capacitor... */
+        const validEncodings = ["utf8", "ascii", "utf16"];
+        if (!validEncodings.includes(data.encoding)) {
+            errors.push(`invalid encoding: ${data.encoding}. validEncodings: ${validEncodings.join(', ')} (E: b88b909521db42cbae684c2937c77079)`);
+        }
+
+        // ensure ib matches up with internal data
+        const { spaceClassname, spaceId, spaceName } = parseSpaceIb({ spaceIb: ib });
+        if (data.classname && (spaceClassname !== data.classname)) {
+            errors.push(`ib's spaceClassname (${spaceClassname}) must match data.classname (${data.classname}) (E: 913b8b98717647fea832e4cca80d8ee6)`);
+        }
+        if (spaceId !== data.uuid) {
+            errors.push(`ib's spaceId (${spaceId}) must match data.uuid (${data.uuid}) (E: b20f36f32bc244008b4df856f892a62a)`);
+        }
+        if (spaceName !== data.name) {
+            errors.push(`ib's spaceName (${spaceName}) must match data.name (${data.name}) (E: cf599a9bf875464d9ec99c79cdee0452)`);
+        }
+
+        // ensure rel8ns make sense
+        if (data.n === undefined && (rel8ns?.past ?? []).length > 0) {
+            errors.push(`"past" rel8n not expected when data.n is falsy (E: 77bb7a90b40a4d989a9e53053776be86)`);
+        }
+        if (data.n && (rel8ns?.past ?? []).length === 0) {
+            errors.push(`"past" rel8n required when data.n is truthy (E: 735e07bac58b44deb2523e3d349d5479)`);
+        }
+        if (data.n === 0 && (rel8ns?.past ?? []).length !== 1) {
+            errors.push(`"past" rel8n expected to have a single record when data.n === 0 (E: 8915bb8084414d3b810cff9bccfc3ec6)`);
+        }
+        if (rel8ns && (rel8ns.past?.length ?? -1) > 0) {
+            const pastAddrs = rel8ns.past as IbGibAddr[];
+            pastAddrs.forEach(x => {
+                const { ib: pastIb } = getIbAndGib({ ibGibAddr: x });
+                const pastIbInfo = parseSpaceIb({ spaceIb: pastIb });
+                if (pastIbInfo.spaceClassname && (pastIbInfo.spaceClassname !== spaceClassname)) {
+                    errors.push(`rel8ns.past address classname (${pastIbInfo.spaceClassname}) must match current spaceClassname (${spaceClassname}) (E: 10b2f05597574558ad2f20db8e471a44)`);
+                }
+                if (pastIbInfo.spaceId !== spaceId) {
+                    errors.push(`rel8ns.past address spaceId (${pastIbInfo.spaceId}) must match current spaceId (${spaceId}) (E: 78b665a31fc34c68be3884d4cd4da35a)`);
+                }
+                // i want to allow this, but for now we're going to require not changing the name...
+                if (pastIbInfo.spaceName !== spaceName) {
+                    errors.push(`rel8ns.past address spaceName (${pastIbInfo.spaceName}) must match current spaceName (${spaceName}) (E: 8a6621cbec9e48e7b6d880375c444bfe)`);
+                }
+            });
+        }
+
+        return errors;
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * gets the data and encoding of a given {@link inputPath} if that file exists.
+ * if it doesn't exist, this will throw an ENOENT error, but this is not logged
+ * as an error.
+ *
+ * this is because atow (03/2024) this is only used in a tryRead_bin function
+ * where the file often does not exist.
+ */
+export async function getFileDataAndEncoding({
+    inputPath,
+    encodingsToTry = B2TFS_DEFAULT_ENCODINGS_TO_TRY,
+}: {
+    inputPath: string,
+    encodingsToTry?: (FileEncoding | undefined)[],
+}): Promise<FileDataInfo> {
+    const lc = `[${getFileDataAndEncoding.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: b4688e6e5f28efa9ed95729f10a6df24)`); }
+
+        let resDataAndEncoding: FileDataInfo | undefined = undefined;
+        const dataBuffer = await readFile(inputPath);
+
+        if (dataBuffer.length === 0) {
+            console.warn(`${lc} file at inputPath (${inputPath}) has dataBuffer.length === 0, i.e., no data content. we are treating this as utf8. (W: 2ea55367538146d695482cfb6ec1b79a)`)
+            return {
+                inputPath,
+                dataBuffer,
+                detectedEncoding: 'utf8',
+                dataString: '',
+            }; /* <<<< returns early */
+        }
+
+        encodingsToTry ??= B2TFS_DEFAULT_ENCODINGS_TO_TRY;
+
+        const tryEncoding = async (encoding: FileEncoding | undefined) => {
+            let res: [boolean, string | undefined];
+            try {
+                const str = dataBuffer.toString(encoding ?? undefined);
+                /**
+                 * doesn't include the node.js replacement unicode char
+                 */
+                const isProbablyCorrect = !str.includes('\ufffd');
+                res = [isProbablyCorrect, str];
+                return res;
+            } catch (error) {
+                debugger;
+                res = [false, undefined];
+            }
+            return res;
+        }
+
+        for (let i = 0; i < encodingsToTry.length; i++) {
+            const maybeEncoding = encodingsToTry[i];
+            const [isProbablyCorrectEncoding, dataString] = await tryEncoding(maybeEncoding);
+            if (isProbablyCorrectEncoding) {
+                resDataAndEncoding = {
+                    inputPath,
+                    dataString,
+                    detectedEncoding: maybeEncoding,
+                    dataBuffer,
+                };
+                break;
+            }
+        }
+
+        if (!resDataAndEncoding) {
+            debugger; // !resDataAndEncoding -> want to see why resDataAndEncoding is still undefined
+            throw new Error(`couldn't turn dataBuffer (length: ${dataBuffer.length}) into dataString with encodingsToTry: (${encodingsToTry}). no idea why. (E: 557c7722f2df7703429778662d3ea224)`);
+            // resDataAndEncoding = {
+            //     inputPath,
+            //     detectedEncoding: undefined,
+            //     dataString: undefined,
+            //     dataBuffer,
+            // }
+        }
+
+        return resDataAndEncoding;
+    } catch (error) {
+        // i'm just suppressing ENOENT at this time because in context, this is
+        // often the case. we do, however, rethrow the error for proper flow.
+        const emsg = extractErrorMsg(error);
+        if (!emsg.startsWith('ENOENT:')) { console.error(`${lc} ${emsg}`); }
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/witness/space/node-filesystem-space/node-filesystem-space-types.mts

@@ -0,0 +1,150 @@
+/**
+ * @module node-filesystem-space-types
+ *
+ * mostly interfaces, some constants
+ */
+
+import { IbGibRel8ns_V1, } from '@ibgib/ts-gib/dist/V1/index.mjs';
+
+import { DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS, IBGIB_SPACE_NAME_DEFAULT, ZERO_SPACE_ID } from '@ibgib/core-gib/dist/witness/space/space-constants.mjs';
+import {
+    IBGIB_BASE_SUBPATH, IBGIB_SPACE_SUBPATH_DEFAULT, IBGIB_BASE_DIR,
+    IBGIB_ENCODING, IBGIB_IBGIBS_SUBPATH, IBGIB_META_SUBPATH,
+    IBGIB_BIN_SUBPATH, IBGIB_DNA_SUBPATH,
+    IBGIB_LONG_SUBPATH,
+    DEFAULT_LONG_PATH_LENGTH,
+    DEFAULT_FILESYSTEM_SPACE_DESCRIPTION,
+} from '@ibgib/core-gib/dist/witness/space/filesystem-space/filesystem-constants.mjs';
+import {
+    FilesystemSpaceData_V1,
+    FilesystemSpaceOptionsData, FilesystemSpaceOptionsRel8ns, FilesystemSpaceOptionsIbGib,
+    FilesystemSpaceResultData, FilesystemSpaceResultRel8ns, FilesystemSpaceResultIbGib,
+} from '@ibgib/core-gib/dist/witness/space/filesystem-space/filesystem-space-v1.mjs';
+
+
+/**
+ * This is the shape of data about this space itself (not the contained ibgibs' spaces).
+ */
+export interface NodeFilesystemSpaceData_V1 extends FilesystemSpaceData_V1 {
+}
+
+/**
+ * Used in bootstrapping.
+ *
+ * If you change this, please bump the version
+ *
+ * (but of course won't be the end of the world when this doesn't happen).
+ */
+export const DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1: NodeFilesystemSpaceData_V1 = {
+    version: '2',
+    uuid: ZERO_SPACE_ID,
+    name: IBGIB_SPACE_NAME_DEFAULT,
+    classname: 'NodeFilesystemSpace_V1',
+    baseDir: IBGIB_BASE_DIR,
+    encoding: IBGIB_ENCODING,
+    baseSubPath: IBGIB_BASE_SUBPATH,
+    spaceSubPath: IBGIB_SPACE_SUBPATH_DEFAULT,
+    ibgibsSubPath: IBGIB_IBGIBS_SUBPATH,
+    metaSubPath: IBGIB_META_SUBPATH,
+    binSubPath: IBGIB_BIN_SUBPATH,
+    dnaSubPath: IBGIB_DNA_SUBPATH,
+    longSubPath: IBGIB_LONG_SUBPATH,
+    mitigateLongPaths: true,
+    longPathLength: DEFAULT_LONG_PATH_LENGTH,
+    persistOptsAndResultIbGibs: false,
+    validateIbGibAddrsMatchIbGibs: false,
+    longPollingIntervalMs: DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS,
+    allowPrimitiveArgs: false,
+    catchAllErrors: true,
+    description: DEFAULT_FILESYSTEM_SPACE_DESCRIPTION,
+    trace: false,
+}
+
+/** Marker interface atm */
+export interface NodeFilesystemSpaceRel8ns_V1 extends IbGibRel8ns_V1 { }
+
+/**
+ * Space options involve whether we're getting/putting ibgibs categorized as
+ * meta, bin, dna.
+ *
+ * We'll leverage the fact that we don't need to get dna very often, and that
+ * meta ibgibs act differently and are recorded differently.
+ *
+ * For example, we don't necessarily want to keep the past of certain meta
+ * objects, because it may change (and thus grow) too quickly.
+ */
+export interface NodeFilesystemSpaceOptionsData extends FilesystemSpaceOptionsData {
+}
+
+export interface NodeFilesystemSpaceOptionsRel8ns extends FilesystemSpaceOptionsRel8ns {
+}
+
+/** Marker interface atm */
+export interface NodeFilesystemSpaceOptionsIbGib
+    extends FilesystemSpaceOptionsIbGib<NodeFilesystemSpaceOptionsData, NodeFilesystemSpaceOptionsRel8ns> {
+}
+
+/** Marker interface atm */
+export interface NodeFilesystemSpaceResultData extends FilesystemSpaceResultData {
+}
+
+export interface NodeFilesystemSpaceResultRel8ns extends FilesystemSpaceResultRel8ns {
+}
+
+export interface NodeFilesystemSpaceResultIbGib
+    extends FilesystemSpaceResultIbGib<NodeFilesystemSpaceResultData, NodeFilesystemSpaceResultRel8ns> {
+}
+/**
+ * currently i'm just taking this from the definition of node's `Buffer` type.
+ *
+ * ## notes
+ *
+ * * using this with handle-reify-file.mts when reading the file.
+ * * 'binary' may resolve to 'latin1' per SO
+ *   * https://stackoverflow.com/questions/46441667/reading-binary-data-in-node-js
+ */
+export type FileEncoding =
+    | 'ascii'
+    | 'utf8'
+    | 'utf-8'
+    | 'utf16le'
+    | 'ucs2'
+    | 'ucs-2'
+    | 'base64'
+    | 'base64url'
+    | 'latin1'
+    | 'binary'
+    | 'hex';
+export const FileEncoding = {
+    ascii: 'ascii' as FileEncoding,
+    utf8: 'utf8' as FileEncoding,
+    utf_8: 'utf-8' as FileEncoding,
+    ['utf-8']: 'utf-8' as FileEncoding,
+    utf16le: 'utf16le' as FileEncoding,
+    ucs2: 'ucs2' as FileEncoding,
+    ucs_2: 'ucs-2' as FileEncoding,
+    ['ucs-2']: 'ucs-2' as FileEncoding,
+    base64: 'base64' as FileEncoding,
+    base64url: 'base64url' as FileEncoding,
+    latin1: 'latin1' as FileEncoding,
+    binary: 'binary' as FileEncoding,
+    hex: 'hex' as FileEncoding,
+};
+/**
+ * valid file encoding values per {@link FileEncoding}
+ */
+export const FILE_ENCODINGS = Object.values(FileEncoding);
+
+export interface FileDataInfo {
+    inputPath: string;
+    detectedEncoding?: FileEncoding | undefined;
+    dataString?: string | undefined;
+    dataBuffer?: Uint8Array | undefined;
+}
+export const B2TFS_DEFAULT_ENCODINGS_TO_TRY: (FileEncoding | undefined)[] = [
+    FileEncoding.utf8,
+    FileEncoding.utf16le,
+    FileEncoding.base64,
+    FileEncoding.binary,
+    undefined,
+];