@ibgib/core-gib 0.0.58 → 0.0.60

package/dist/witness/space/space-types.mjs

@@ -1,4 +1,82 @@
 import { ENCRYPTION_REL8N_NAME } from '../../common/encrypt/encrypt-constants.mjs';
+export const SpaceLocation = {
+    /**
+     * space is a local space, with lower latency and direct usage with
+     * metaspace. To be used as the primary local user space.
+     *
+     * no real proxy is involved, rather, we should be speaking "directly" with
+     * the local location.
+     */
+    local: 'local',
+    /**
+     * space is an outerspace, with higher latency, probably some kind of proxy
+     * client access. More intended to be used with syncing...
+     */
+    outerspace: 'outerspace',
+    /**
+     * in-memory-only space.
+     *
+     * Note: I haven't really incorporated this, but I have sketched an
+     * in-memory innerspace and in the future, I think this will be heavily
+     * utilized.
+     */
+    innerspace: 'innerspace',
+};
+export const VALID_SPACE_LOCATIONS = Object.values(SpaceLocation).concat();
+export const SpaceType = {
+    /**
+     * user space that usually (always?) acts locally as the main type of
+     * storage for a user.
+     *
+     * This means that the user is actively working in this space, and it isn't
+     * a derivative space. perhaps "source" would be better?
+     */
+    user: 'user',
+    /**
+     * this is a derivative user space that is used to synchronize ibgib
+     * timelines among two or more other spaces.
+     */
+    sync: 'sync',
+};
+/**
+ * Object.values(SpaceType).concat()
+ *
+ * for now, you can add valid space types here in initialization code to
+ * manually extend this.
+ */
+export const VALID_SPACE_TYPES = Object.values(SpaceType).concat();
+/**
+ * specific/concrete subtype implementations
+ */
+export const UserSpaceSubtype = {
+    /**
+     * local user space is driven by a node filesystem concrete implementation.
+     *
+     * Note: This is actually implemented elsewhere, but I am deferring the
+     * additional architectural requirements for putting the node filesystem and
+     * extending this to include it. so I'm just putting this here. But in the
+     * future, this should be moved to a node-specific library and brought in if
+     * the app requires it.
+     */
+    node_filesystem: 'node-filesystem',
+};
+export const SyncSpaceSubtype = {
+    aws_dynamodb: 'aws-dynamodb',
+};
+/**
+ * specific, concrete implementation of space
+ */
+export const SpaceSubtype = {
+    ...UserSpaceSubtype,
+    ...SyncSpaceSubtype,
+};
+/**
+ * Object.values(SpaceSubtype).concat()
+ *
+ * for now, you can add valid subtypes here in initialization code to manually
+ * extend this.
+ */
+export const VALID_SPACE_SUBTYPES = Object.values(SpaceSubtype).concat();
 /** Cmds for interacting with ibgib spaces.  */
 export const IbGibSpaceOptionsCmd = {
     /** Retrieve ibGib(s) out of the space (does not remove them). */

package/dist/witness/space/space-types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"space-types.mjs","sourceRoot":"","sources":["../../../src/witness/space/space-types.mts"],"names":[],"mappings":"AAQA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AA6GnF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,iEAAiE;IACjE,GAAG,EAAE,KAA6B;IAClC,iDAAiD;IACjD,GAAG,EAAE,KAA6B;IAClC,mCAAmC;IACnC,MAAM,EAAE,QAAgC;CAC3C,CAAA;AAOD;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IACxC;;;;OAIG;IACH,GAAG,EAAE,KAAqC;IAC1C;;OAEG;IACH,KAAK,EAAE,OAAuC;IAC9C;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,QAAwC;IAChD;;OAEG;IACH,KAAK,EAAE,OAAuC;IAC9C;;OAEG;IACH,OAAO,EAAE,SAAyC;IAClD;;OAEG;IACH,IAAI,EAAE,MAAsC;CAC/C,CAAA"}
+{"version":3,"file":"space-types.mjs","sourceRoot":"","sources":["../../../src/witness/space/space-types.mts"],"names":[],"mappings":"AAQA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AAUnF,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB;;;;;;OAMG;IACH,KAAK,EAAE,OAAwB;IAC/B;;;OAGG;IACH,UAAU,EAAE,YAA6B;IACzC;;;;;;OAMG;IACH,UAAU,EAAE,YAA6B;CAC5C,CAAA;AACD,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,EAAE,CAAC;AAG3E,MAAM,CAAC,MAAM,SAAS,GAAG;IACrB;;;;;;OAMG;IACH,IAAI,EAAE,MAAmB;IACzB;;;OAGG;IACH,IAAI,EAAE,MAAmB;CAC5B,CAAA;AACD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC;AAGnE;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B;;;;;;;;OAQG;IACH,eAAe,EAAE,iBAAqC;CACzD,CAAA;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B,YAAY,EAAE,cAAkC;CACnD,CAAA;AAGD;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB,GAAG,gBAAgB;IACnB,GAAG,gBAAgB;CACtB,CAAA;AACD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,CAAC;AAgHzE,+CAA+C;AAC/C,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,iEAAiE;IACjE,GAAG,EAAE,KAA6B;IAClC,iDAAiD;IACjD,GAAG,EAAE,KAA6B;IAClC,mCAAmC;IACnC,MAAM,EAAE,QAAgC;CAC3C,CAAA;AAOD;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG;IACxC;;;;OAIG;IACH,GAAG,EAAE,KAAqC;IAC1C;;OAEG;IACH,KAAK,EAAE,OAAuC;IAC9C;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,QAAwC;IAChD;;OAEG;IACH,KAAK,EAAE,OAAuC;IAC9C;;OAEG;IACH,OAAO,EAAE,SAAyC;IAClD;;OAEG;IACH,IAAI,EAAE,MAAsC;CAC/C,CAAA"}

package/dist/witness/witness-constants.d.mts

@@ -1,3 +1,4 @@
+export declare const WITNESS_ATOM = "witness";
 export declare const WITNESS_ARG_METADATA_STRING = "witness_arg";
 export declare const WITNESS_RESULT_METADATA_STRING = "witness_result";
 export declare const WITNESS_CONTEXT_REL8N_NAME = "context";

package/dist/witness/witness-constants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"witness-constants.d.mts","sourceRoot":"","sources":["../../src/witness/witness-constants.mts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,gBAAgB,CAAC;AACzD,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAE/D,eAAO,MAAM,0BAA0B,YAAY,CAAC"}
+{"version":3,"file":"witness-constants.d.mts","sourceRoot":"","sources":["../../src/witness/witness-constants.mts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,YAAY,CAAC;AACtC,eAAO,MAAM,2BAA2B,gBAAgB,CAAC;AACzD,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAE/D,eAAO,MAAM,0BAA0B,YAAY,CAAC"}

package/dist/witness/witness-constants.mjs

@@ -1,3 +1,4 @@
+export const WITNESS_ATOM = 'witness';
 export const WITNESS_ARG_METADATA_STRING = 'witness_arg';
 export const WITNESS_RESULT_METADATA_STRING = 'witness_result';
 export const WITNESS_CONTEXT_REL8N_NAME = 'context';

package/dist/witness/witness-constants.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"witness-constants.mjs","sourceRoot":"","sources":["../../src/witness/witness-constants.mts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,2BAA2B,GAAG,aAAa,CAAC;AACzD,MAAM,CAAC,MAAM,8BAA8B,GAAG,gBAAgB,CAAC;AAE/D,MAAM,CAAC,MAAM,0BAA0B,GAAG,SAAS,CAAC"}
+{"version":3,"file":"witness-constants.mjs","sourceRoot":"","sources":["../../src/witness/witness-constants.mts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC;AACtC,MAAM,CAAC,MAAM,2BAA2B,GAAG,aAAa,CAAC;AACzD,MAAM,CAAC,MAAM,8BAA8B,GAAG,gBAAgB,CAAC;AAE/D,MAAM,CAAC,MAAM,0BAA0B,GAAG,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/core-gib",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "description": "ibgib core functionality, including base architecture for witnesses, spaces, apps, robbots, etc., as well as shared utility functions. Node v19+ needed for heavily-used isomorphic webcrypto hashing consumed in both node and browsers.",
   "repository": {
     "url": "https://gitlab.com/ibgib/core-gib",
@@ -53,7 +53,7 @@
   "dependencies": {
     "@ibgib/encrypt-gib": "^0.2.25",
     "@ibgib/helper-gib": "^0.0.22",
-    "@ibgib/ts-gib": "^0.5.10"
+    "@ibgib/ts-gib": "^0.5.11"
   },
   "devDependencies": {
     "@types/node": "^20.2.1"

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

@@ -1652,6 +1652,11 @@ export abstract class MetaspaceBase implements MetaspaceService {
     }: {
         secretIbGibs: IbGib_V1<SecretData_V1>[],
         fnPromptPassword: (title: string, msg: string) => Promise<string | null>,
+        /**
+         * i think this was added because I didn't want it prompting in the
+         * background in case we were trying to sync in the background and the
+         * user hadn't entered the password (and cached it).
+         */
         dontPrompt?: boolean,
         checkCacheFirst?: boolean,
         cacheAfter?: boolean,

package/src/witness/space/outer-space/outer-space-helper.mts

@@ -11,11 +11,8 @@
 
 import { Ib, } from '@ibgib/ts-gib/dist/types.mjs';
 
-import {
-    OuterSpaceSubtype, OuterSpaceType,
-    StatusCode, StatusIbInfo,
-    VALID_OUTER_SPACE_SUBTYPES, VALID_OUTER_SPACE_TYPES,
-} from './outer-space-types.mjs';
+import { SpaceType, SpaceSubtype, VALID_SPACE_SUBTYPES, VALID_SPACE_TYPES, } from '../space-types.mjs';
+import { StatusCode, StatusIbInfo, } from './outer-space-types.mjs';
 import { OUTER_SPACE_DEFAULT_IB_DELIMITER } from './outer-space-constants.mjs';
 
 
@@ -75,13 +72,13 @@ export function getStatusIbInfo({
         const statusCode = pieces[2] as StatusCode; // tenatively cast as StatusCode
         if (!Object.values(StatusCode).includes(statusCode)) { throw new Error(`invalid/unknown status code (${statusCode}) (E: 7580860df7b344b3992148552e80a85e)`); }
 
-        const spaceType = pieces[3] as OuterSpaceType;
+        const spaceType = pieces[3] as SpaceType;
         if (spaceType === null || spaceType === undefined) { throw new Error(`spaceType is null/undefined. (E: 12473d35e77b451bb59bb05c03cb8b64)`); }
-        if (!VALID_OUTER_SPACE_TYPES.includes(spaceType)) { throw new Error(`invalid/unknown spaceType (${spaceType}) (E: d3ba9add427f49dda34f265f3225d9db)`); }
+        if (!VALID_SPACE_TYPES.includes(spaceType)) { throw new Error(`invalid/unknown spaceType (${spaceType}) (E: d3ba9add427f49dda34f265f3225d9db)`); }
 
-        const spaceSubtype = pieces[4] as OuterSpaceSubtype;
+        const spaceSubtype = pieces[4] as SpaceSubtype;
         if (spaceSubtype === null || spaceSubtype === undefined) { throw new Error(`spaceSubtype is null/undefined. (E: 6da7ae919d0b4a22b4ee685520b6c946)`); }
-        if (!VALID_OUTER_SPACE_SUBTYPES.includes(spaceSubtype)) { throw new Error(`invalid/unknown spaceSubtype (${spaceSubtype}) (E: 703ed1aee44447a294b3e1cf0984baba)`); }
+        if (!VALID_SPACE_SUBTYPES.includes(spaceSubtype)) { throw new Error(`invalid/unknown spaceSubtype (${spaceSubtype}) (E: 703ed1aee44447a294b3e1cf0984baba)`); }
 
         return { statusCode, spaceType, spaceSubtype, sagaId, delimiter };
     } catch (error) {

package/src/witness/space/outer-space/outer-space-types.mts

@@ -16,7 +16,7 @@ import {
     IbGibSpaceData, IbGibSpaceRel8ns,
     IbGibSpaceOptionsData, IbGibSpaceOptionsRel8ns, IbGibSpaceOptionsIbGib,
     IbGibSpaceOptionsCmdModifier,
-    IbGibSpaceResultData, IbGibSpaceResultRel8ns, IbGibSpaceResultIbGib,
+    IbGibSpaceResultData, IbGibSpaceResultRel8ns, IbGibSpaceResultIbGib, SyncSpaceSubtype, SpaceType, SpaceSubtype,
 } from '../space-types.mjs';
 import { IbGibSpaceAny } from '../space-base-v1.mjs';
 import { CIPHERTEXT_REL8N_NAME } from '../../../common/encrypt/encrypt-constants.mjs';
@@ -124,33 +124,7 @@ export const StatusCode = {
     completed: 'completed' as StatusCode,
 }
 
-export type OuterSpaceType = "sync";
-export const OuterSpaceType = {
-    sync: 'sync' as OuterSpaceType,
-}
-export const VALID_OUTER_SPACE_TYPES = Object.values(OuterSpaceType).concat();
-
-export type SyncSpaceSubtype =
-    'aws-dynamodb' |
-    'local-machine-node';
-export const SyncSpaceSubtype = {
-    aws_dynamodb: 'aws-dynamodb' as SyncSpaceSubtype,
-    /**
-     * not implemented yet
-     */
-    local_machine_node: 'local-machine-node' as SyncSpaceSubtype,
-}
-
-export type OuterSpaceSubtype = 'tbd' | SyncSpaceSubtype;
-export const OuterSpaceSubtype = {
-    tbd: 'tbd' as OuterSpaceSubtype,
-    ...SyncSpaceSubtype,
-}
-export const VALID_OUTER_SPACE_SUBTYPES = Object.values(OuterSpaceSubtype).concat();
-
 export interface OuterSpaceData extends IbGibSpaceData {
-    type: OuterSpaceType;
-    subtype: OuterSpaceSubtype;
 }
 
 export interface OuterSpaceRel8ns extends IbGibSpaceRel8ns {
@@ -171,6 +145,9 @@ export interface SyncSpaceData extends OuterSpaceData {
 }
 export interface SyncSpaceRel8ns extends OuterSpaceRel8ns {
 }
+export interface SyncSpaceIbGib
+    extends IbGib_V1<SyncSpaceData, SyncSpaceRel8ns> {
+}
 
 /**
  * this is the info about the **space**, as in the space participates in the
@@ -664,8 +641,8 @@ export interface StatusIbInfo {
      *
      */
     statusCode: StatusCode,
-    spaceType: OuterSpaceType,
-    spaceSubtype: OuterSpaceSubtype,
+    spaceType: SpaceType,
+    spaceSubtype: SpaceSubtype,
     sagaId: string,
     delimiter?: string,
 }

package/src/witness/space/space-constants.mts

@@ -118,6 +118,11 @@ export const DEFAULT_SPACE_REL8N_NAME = 'x';
 export const DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS = 30_000;
 export const DEFAULT_LOCAL_SPACE_POLLING_DELAY_FIRST_RUN_MS = 10_000;
 
+/**
+ * it's a space
+ */
+export const SPACE_ATOM = 'space';
+
 /**
  * {@link DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS} but for outer spaces, so
  * longer interval atow.

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

@@ -14,22 +14,18 @@ import { getGib, getGibInfo, } from '@ibgib/ts-gib/dist/V1/transforms/transform-
 import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
 import { APP_REL8N_NAME } from '../app/app-constants.mjs';
 import {
-    GetIbGibOpts, GetIbGibResult,
-    PutIbGibOpts, PutIbGibResult,
-    DeleteIbGibOpts, DeleteIbGibResult, SpecialIbGibType,
-    IbGibTimelineUpdateInfo,
+    GetIbGibOpts, GetIbGibResult, PutIbGibOpts, PutIbGibResult, DeleteIbGibOpts,
+    DeleteIbGibResult, SpecialIbGibType, IbGibTimelineUpdateInfo,
 } from '../../common/other/other-types.mjs';
 import {
-    getRootIb,
-    getSpecialConfigKey, getSpecialIbGibAddr, getSpecialIbGibIb, getSpecialTypeFromIb,
-    getTjpAddr, isSpecial, isTjp_Naive, tagTextToIb
+    getRootIb, getSpecialConfigKey, getSpecialIbGibIb,
+    getSpecialTypeFromIb, getTjpAddr, isSpecial, isTjp_Naive, tagTextToIb
 } from '../../common/other/ibgib-helper.mjs';
 import { TagData_V1, TagIbGib_V1 } from '../../common/tag/tag-types.mjs';
 import { BOOTSTRAP_DATA_DEFAULT_SPACE_ID_KEY, BOOTSTRAP_DATA_KNOWN_SPACE_IDS_KEY, BOOTSTRAP_IBGIB_ADDR } from './bootstrap/bootstrap-constants.mjs';
 import {
-    SpaceLockScope, IbGibSpaceLockIbGib, SpaceId,
-    IbGibSpaceLockOptions, TxId,
-    IbGibSpaceResultIbGib, IbGibSpaceResultData, IbGibSpaceResultRel8ns
+    SpaceLockScope, IbGibSpaceLockIbGib, SpaceId, IbGibSpaceLockOptions, TxId,
+    IbGibSpaceResultIbGib, IbGibSpaceResultData, IbGibSpaceResultRel8ns, SpaceType, SpaceSubtype, VALID_SPACE_TYPES, VALID_SPACE_SUBTYPES
 } from './space-types.mjs';
 import { getAppIb, } from '../app/app-helper.mjs';
 import { AppData_V1, AppIbGib_V1 } from '../app/app-types.mjs';
@@ -40,19 +36,21 @@ import { IbGibSpaceAny } from './space-base-v1.mjs';
 import { RootData } from '../../common/root/root-types.mjs';
 import { IbGibCacheService } from '../../common/cache/cache-types.mjs';
 import {
-    DEFAULT_MAX_DELAY_MS_RETRY_LOCK_ACQUIRE, DEFAULT_MAX_DELAY_RETRY_LOCK_ACQUIRE_ATTEMPTS,
-    DEFAULT_SECONDS_VALID_LOCAL, DEFAULT_TX_ID_LENGTH, IBGIB_SPACE_NAME_DEFAULT,
+    DEFAULT_MAX_DELAY_MS_RETRY_LOCK_ACQUIRE,
+    DEFAULT_MAX_DELAY_RETRY_LOCK_ACQUIRE_ATTEMPTS, DEFAULT_SECONDS_VALID_LOCAL,
+    DEFAULT_TX_ID_LENGTH, IBGIB_SPACE_NAME_DEFAULT, SPACE_ATOM,
     SPACE_LOCK_IB_TERM, SYNC_SPACE_REL8N_NAME,
 } from './space-constants.mjs';
 import { DEFAULT_TAG_DESCRIPTION, DEFAULT_TAG_ICON, TAG_REL8N_NAME } from '../../common/tag/tag-constants.mjs';
 import {
-    DEFAULT_ROOT_DESCRIPTION, DEFAULT_ROOT_ICON,
-    DEFAULT_ROOT_REL8N_NAME, DEFAULT_ROOT_TEXT, ROOT_REL8N_NAME
+    DEFAULT_ROOT_DESCRIPTION, DEFAULT_ROOT_ICON, DEFAULT_ROOT_REL8N_NAME,
+    DEFAULT_ROOT_TEXT, ROOT_REL8N_NAME
 } from '../../common/root/root-constants.mjs';
 import { ARCHIVE_REL8N_NAME, TRASH_REL8N_NAME } from '../../common/other/other-constants.mjs';
 import { validateBootstrapIbGib } from './bootstrap/bootstrap-helper.mjs';
 import { BootstrapData, BootstrapIbGib, BootstrapRel8ns } from './bootstrap/bootstrap-types.mjs';
-import { getMetaStoneIb, newUpMetaStone } from '../../common/meta-stone/meta-stone-helper.mjs';
+import { newUpMetaStone } from '../../common/meta-stone/meta-stone-helper.mjs';
+import { WITNESS_ATOM } from '../witness-constants.mjs';
 
 let logalot = GLOBAL_LOG_A_LOT;
 
@@ -3049,57 +3047,61 @@ export function getSpaceIb({
     try {
         if (!space) { throw new Error(`space required (E: 4dabec34ee77d67c9cc30ee3c3049622)`); }
         if (!space.data) { throw new Error(`space.data required (E: 058d298876ebbeada7bbddb9e3da2f23)`); }
-        classname ||= space?.data!.classname;
+
+        if (classname && space.data.classname && classname !== space.data.classname) {
+            throw new Error(`both classname arg (${classname}) and space.data.classname (${space.data.classname}) are different truthy values. (E: f98f012ee876eb8fbe7403f7b53e4624)`);
+        } else {
+            classname ||= space?.data!.classname;
+        }
         if (!classname) { throw new Error(`classname required (E: fa3af4613ad56742dab51d1b0d839322)`); }
-        if (classname.includes(' ')) { throw new Error(`invalid classname. cannot contain spaces (E: 243adbf720dcce7904e2665933208b22)`); }
+        if (classname.includes(' ')) { throw new Error(`invalid classname (${classname}). cannot contain spaces (E: 243adbf720dcce7904e2665933208b22)`); }
+
         const name = space.data?.name || IBGIB_SPACE_NAME_DEFAULT;
         if (name.includes(' ')) { throw new Error(`invalid space name. cannot contain spaces (E: a8450e1651081412c8ac018520182422)`); }
+
         const id = space.data?.uuid || undefined;
         if (!id) { throw new Error(`invalid space, space.data.uuid falsy (E: 50ae723a9ab24f4fc7132613e65faf23)`); }
         if (id.includes(' ')) { throw new Error(`invalid space id. cannot contain spaces (E: 8696830fe7f54bfa85e670a063f3e089)`); }
-        let ib = `witness space ${classname} ${name} ${id}`;
-        return ib;
+
+        const spaceType = space.data.type ?? undefined;
+        const spaceSubtype = space.data.subtype ?? undefined;
+        if (spaceType && !spaceSubtype) {
+            throw new Error(`spaceType (${spaceType}) is set but spaceSubtype is falsy. (E: 878ab960d7987ae2331103b4a00d0d24)`);
+        }
+
+        return `${WITNESS_ATOM} ${SPACE_ATOM} ${classname} ${name} ${id} ${spaceType} ${spaceSubtype}`;
     } catch (error) {
         console.error(`${lc} ${error.message}`);
         throw error;
     }
 }
 
+/**
+ * determines if the given ib belongs to a space ibgib.
+ *
+ * atow (03/2024) checks to see if the ib starts with
+ *
+ *   `${WITNESS_ATOM} ${SPACE_ATOM} `
+ */
 export function isSpaceIb({
     ib
 }: {
     ib: Ib
 }): boolean {
     const lc = `[${isSpaceIb.name}]`;
-    try {
-        if (logalot) { console.log(`${lc} starting... (I: 53ad337f8148616a77caca5dff0f8722)`); }
-        return ib.startsWith('witness space ') || ib.startsWith('outerspace sync ');
-    } catch (error) {
-        console.error(`${lc} ${error.message}`);
-        throw error;
-    } finally {
-        if (logalot) { console.log(`${lc} complete.`); }
+    if (!ib) {
+        const emsg = `${lc} ib required (E: dd5244f62f964359a86e59bb08ee47e6)`;
+        console.error(emsg);
+        throw new Error(emsg);
     }
+    return ib.startsWith(`${WITNESS_ATOM} ${SPACE_ATOM} `);
+    // return ib.startsWith('witness space ') || ib.startsWith('outerspace sync ');
 }
 
 /**
- * ## current schema FOR LOCAL (IONIC) SPACES:
- *
- * `witness space [classname] [spaceName] [spaceId]`
- *
- * ## current schema FOR SYNC (AWS) OUTERSPACES (was in create outer space modal form code):
- *
- * `outerspace sync [spaceName]
- *
- * ## I need to fix this somehow...
+ * atow (03/2024), (space-delimited) schema is...
  *
- * This is why I'm working on streamlining space management
- *
- * (To start with, I just had to get the ball rolling and tried my best.)
- *
- * ## NOTES
- *
- * * both schemas are space-delimited
+ * `${WITNESS_ATOM} ${SPACE_ATOM} ${classname} ${name} ${id} ${spaceType} ${spaceSubtype}`
  */
 export function parseSpaceIb({
     spaceIb,
@@ -3122,28 +3124,53 @@ export function parseSpaceIb({
      * (for better or worse)
      */
     spaceId: SpaceId | undefined,
+    /**
+     * if undefined, by convention, this is a user space
+     */
+    spaceType: SpaceType | undefined,
+    /**
+     * subtype, if applicable
+     */
+    spaceSubtype: SpaceSubtype | undefined,
 } {
     const lc = `[${parseSpaceIb.name}]`;
     try {
         if (!spaceIb) { throw new Error(`spaceIb required (E: fa5424cfb7e846e2851562f2f417944f)`); }
 
-        if (spaceIb.startsWith('witness space ')) {
-            const pieces = spaceIb.split(' ');
-            if (pieces.length < 4) { throw new Error(`space ib must have at least 3 components: witness, space, classname, name (E: e42296b41496ee99754a1f3d55dd8323)`); }
-            return {
-                spaceClassname: pieces[2],
-                spaceName: pieces[3],
-                spaceId: pieces[4],
-            };
-        } else if (spaceIb.startsWith('outerspace sync ')) {
-            const pieces = spaceIb.split(' ');
-            return {
-                spaceClassname: undefined,
-                spaceName: pieces[2],
-                spaceId: undefined,
-            };
-        } else {
-            throw new Error(`unknown spaceIb schema (spaceIb: ${spaceIb}) (E: a6d361be85d5f25d6a464a5896186322)`);
+        //  `${WITNESS_ATOM} ${SPACE_ATOM} ${classname} ${name} ${id} ${spaceType} ${spaceSubtype}`
+        const [witnessAtom, spaceAtom, spaceClassname, spaceName, spaceId, spaceType_string, spaceSubtype_string] =
+            spaceIb.split(' ');
+
+        if (witnessAtom !== WITNESS_ATOM) { throw new Error(`invalid spaceIb (${spaceIb}). witnessAtom !== WITNESS_ATOM (E: 5ae1ca12cf8f30ae341f3e582b025224)`); }
+        if (spaceAtom !== SPACE_ATOM) { throw new Error(`invalid spaceIb (${spaceIb}). spaceAtom !== SPACE_ATOM (E: 9cc6b6f30e13455eb29748148a94fa0f)`); }
+        if (!spaceClassname) { throw new Error(`invalid spaceIb (${spaceIb}). spaceClassname falsy (E: 00d3392da007ca8b2840b16b199d9a24)`); }
+        if (!spaceName) { throw new Error(`invalid spaceIb (${spaceIb}). spaceName falsy (E: b957d8e74ef34d889fa64c60c7a5ea0b)`); }
+        if (!spaceId) { throw new Error(`invalid spaceIb (${spaceIb}). spaceId falsy (E: 7a1773722d8e46a0866d683130b65b89)`); }
+
+        let spaceType: SpaceType | undefined = undefined;
+        if (spaceType_string && spaceType_string !== 'undefined') {
+            if (VALID_SPACE_TYPES.includes(spaceType_string as SpaceType)) {
+                spaceType = spaceType_string as SpaceType;
+            } else {
+                throw new Error(`invalid spaceIb (${spaceIb}). spaceType (${spaceType_string}) is set but not a valid type. valid types: ${VALID_SPACE_TYPES.join(', ')} (E: 838f4638a88cfbf3545a3a3a38b6dd24)`);
+            }
+        }
+
+        let spaceSubtype: SpaceSubtype | undefined = undefined;
+        if (spaceSubtype_string && spaceSubtype_string !== 'undefined') {
+            if (VALID_SPACE_SUBTYPES.includes(spaceSubtype_string as SpaceSubtype)) {
+                spaceSubtype = spaceSubtype_string as SpaceSubtype;
+            } else {
+                throw new Error(`invalid spaceIb (${spaceIb}). spaceSubtype (${spaceSubtype_string}) is set but not a valid subtype. valid subtypes: ${VALID_SPACE_SUBTYPES.join(', ')} (E: 5bdcf23027f94e73860e4340313b04ab)`);
+            }
+        }
+
+        return {
+            spaceClassname,
+            spaceName,
+            spaceId,
+            spaceType,
+            spaceSubtype,
         }
     } catch (error) {
         console.error(`${lc} ${error.message}`);

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

@@ -15,6 +15,93 @@ import { WitnessCmdData, WitnessCmdIbGib, WitnessCmdRel8ns, } from '../witness-c
  */
 export type SpaceId = string;
 
+export type SpaceLocation = "local" | "sync";
+export const SpaceLocation = {
+    /**
+     * space is a local space, with lower latency and direct usage with
+     * metaspace. To be used as the primary local user space.
+     *
+     * no real proxy is involved, rather, we should be speaking "directly" with
+     * the local location.
+     */
+    local: 'local' as SpaceLocation,
+    /**
+     * space is an outerspace, with higher latency, probably some kind of proxy
+     * client access. More intended to be used with syncing...
+     */
+    outerspace: 'outerspace' as SpaceLocation,
+    /**
+     * in-memory-only space.
+     *
+     * Note: I haven't really incorporated this, but I have sketched an
+     * in-memory innerspace and in the future, I think this will be heavily
+     * utilized.
+     */
+    innerspace: 'innerspace' as SpaceLocation,
+}
+export const VALID_SPACE_LOCATIONS = Object.values(SpaceLocation).concat();
+
+export type SpaceType = "user" | "sync";
+export const SpaceType = {
+    /**
+     * user space that usually (always?) acts locally as the main type of
+     * storage for a user.
+     *
+     * This means that the user is actively working in this space, and it isn't
+     * a derivative space. perhaps "source" would be better?
+     */
+    user: 'user' as SpaceType,
+    /**
+     * this is a derivative user space that is used to synchronize ibgib
+     * timelines among two or more other spaces.
+     */
+    sync: 'sync' as SpaceType,
+}
+/**
+ * Object.values(SpaceType).concat()
+ *
+ * for now, you can add valid space types here in initialization code to
+ * manually extend this.
+ */
+export const VALID_SPACE_TYPES = Object.values(SpaceType).concat();
+
+export type UserSpaceSubtype = 'node-filesystem';
+/**
+ * specific/concrete subtype implementations
+ */
+export const UserSpaceSubtype = {
+    /**
+     * local user space is driven by a node filesystem concrete implementation.
+     *
+     * Note: This is actually implemented elsewhere, but I am deferring the
+     * additional architectural requirements for putting the node filesystem and
+     * extending this to include it. so I'm just putting this here. But in the
+     * future, this should be moved to a node-specific library and brought in if
+     * the app requires it.
+     */
+    node_filesystem: 'node-filesystem' as UserSpaceSubtype,
+}
+export type SyncSpaceSubtype = 'aws-dynamodb';
+export const SyncSpaceSubtype = {
+    aws_dynamodb: 'aws-dynamodb' as SyncSpaceSubtype,
+}
+
+export type SpaceSubtype = UserSpaceSubtype | SyncSpaceSubtype; // extend with logical OR types here
+/**
+ * specific, concrete implementation of space
+ */
+export const SpaceSubtype = {
+    ...UserSpaceSubtype,
+    ...SyncSpaceSubtype,
+}
+/**
+ * Object.values(SpaceSubtype).concat()
+ *
+ * for now, you can add valid subtypes here in initialization code to manually
+ * extend this.
+ */
+export const VALID_SPACE_SUBTYPES = Object.values(SpaceSubtype).concat();
+
 /**
  * Common data among all ibgib spaces.
  */
@@ -32,6 +119,16 @@ export interface IbGibSpaceData extends WitnessData_V1 {
      * field.
      */
     uuid: SpaceId;
+    /**
+     * if not given, defaults to "user" by convention.
+     * @see {@link SpaceType}
+     */
+    type?: SpaceType;
+    /**
+     * should be required if {@link type} is set (truthy).
+     * @see {@link SpaceSubtype}
+     */
+    subtype?: SpaceSubtype | undefined;
     /**
      * If true, when this space receives a command that includes incoming ibGibs
      * and ibGibAddrs, we will ensure the ibGibs have a 1-to-1 correspondence to

package/src/witness/witness-constants.mts

@@ -1,3 +1,4 @@
+export const WITNESS_ATOM = 'witness';
 export const WITNESS_ARG_METADATA_STRING = 'witness_arg';
 export const WITNESS_RESULT_METADATA_STRING = 'witness_result';