mftsccs-browser 2.1.239-dev → 2.1.240-dev

package/dist/types/Services/Local/CreateTheConnectionLocal.d.ts

@@ -0,0 +1,140 @@
+import { Concept, InnerActions } from "../../app";
+/**
+ * Creates a connection in local storage (IndexedDB) without syncing to the backend.
+ *
+ * This is the primary function for creating offline-first connections. The connection is stored
+ * locally in IndexedDB and memory, but NOT immediately sent to the backend. Sync happens
+ * later via LocalSyncData.SyncDataOnline().
+ *
+ * **Virtual ID System:**
+ * - Generates a negative ID (e.g., -67890) to indicate local/virtual status
+ * - id and ghostId are initially equal and both negative
+ * - After backend sync: id becomes positive (real backend ID)
+ * - ghostId remains negative (preserves original local ID)
+ * - Mapping is stored in backend and LocalGhostIdTree
+ *
+ * **Connection Types:**
+ * - **Internal Connections**: orderId < 3 (within a composition)
+ *   - typeId is typically the composition ID
+ * - **External Connections**: orderId >= 999 (between different entities)
+ *   - typeId is a type concept ID
+ *   - typeString provides human-readable type name
+ *
+ * **Self-Connection Prevention:**
+ * If ofTheConceptId equals toTheConceptId, returns an empty connection (prevents loops).
+ *
+ * @param ofTheConceptId - Source concept ID (FROM). The connection originates here.
+ *                        Can be negative (local) or positive (server) ID.
+ * @param toTheConceptId - Target concept ID (TO). The connection points here.
+ *                        Can be negative (local) or positive (server) ID.
+ * @param typeId - The type classification for this connection.
+ *                - For internal connections: composition ID
+ *                - For external connections: type concept ID
+ * @param orderId - Order identifier for sorting multiple connections.
+ *                 - < 3: Internal connection
+ *                 - >= 999: External connection
+ *                 - Defaults to 1
+ * @param typeString - Human-readable type name (e.g., "the_person_email").
+ *                    Used primarily for external connections. Defaults to empty string.
+ * @param userId - The ID of the user creating this connection. Defaults to 999 (system).
+ * @param actions - Action tracking object that accumulates created concepts and connections.
+ *                 Used for batch operations and rollback. Defaults to empty arrays.
+ *
+ * @returns Promise resolving to the created Connection object with negative ID.
+ *         Returns empty connection (all IDs = 0) if self-connection attempted.
+ *
+ * @example
+ * // Create internal connection (within composition)
+ * const internalConn = await CreateTheConnectionLocal(
+ *   projectId,    // -12345
+ *   taskId,       // -67890
+ *   compositionId,// -11111
+ *   1,            // orderId < 3 = internal
+ *   "",           // no typeString needed
+ *   101           // userId
+ * );
+ * console.log(internalConn.id); // -99999 (negative = local)
+ *
+ * @example
+ * // Create external connection (between entities)
+ * const externalConn = await CreateTheConnectionLocal(
+ *   personId,           // 123
+ *   emailId,            // 456
+ *   emailTypeId,        // 789
+ *   1000,               // orderId >= 999 = external
+ *   "the_person_email", // typeString for external
+ *   101
+ * );
+ *
+ * @example
+ * // Track actions for batch operations
+ * const actions = { concepts: [], connections: [] };
+ * await CreateTheConnectionLocal(id1, id2, typeId, 1, "", 101, actions);
+ * await CreateTheConnectionLocal(id2, id3, typeId, 1, "", 101, actions);
+ * console.log(actions.connections.length); // 2
+ * // All created connections tracked for potential rollback
+ *
+ * @example
+ * // Self-connection prevention
+ * const selfConn = await CreateTheConnectionLocal(123, 123, 5, 1);
+ * console.log(selfConn.id); // 0 (empty connection, prevented)
+ *
+ * @throws Logs errors and re-throws for handling by caller
+ *
+ * @see {@link CreateConnection} for simplified connection creation with concepts
+ * @see {@link LocalSyncData} for syncing local connections to backend
+ * @see {@link createTheConnection} for creating server-synced connections directly
+ */
+export declare function CreateTheConnectionLocal(ofTheConceptId: number, toTheConceptId: number, typeId: number, orderId?: number, typeString?: string, userId?: number, actions?: InnerActions): Promise<any>;
+/**
+ * Simplified connection creator that accepts concepts and a type string.
+ *
+ * This is a convenience wrapper around CreateTheConnectionLocal that:
+ * 1. Accepts Concept objects instead of IDs
+ * 2. Creates the connection type concept if it doesn't exist
+ * 3. Extracts necessary IDs automatically
+ * 4. Sets appropriate defaults for local connections
+ *
+ * **Advantages:**
+ * - More intuitive API (pass concepts, not IDs)
+ * - Automatic type concept creation/retrieval
+ * - Less boilerplate code
+ * - Type-safe with TypeScript
+ *
+ * **Process:**
+ * 1. Creates/retrieves type concept from connectionTypeString
+ * 2. Extracts userId from source concept
+ * 3. Calls CreateTheConnectionLocal with extracted IDs
+ * 4. Returns the created connection
+ *
+ * @param ofTheConcept - The source Concept object (FROM)
+ * @param toTheConcept - The target Concept object (TO)
+ * @param connectionTypeString - Type name as string (e.g., "the_person_email").
+ *                              A type concept will be created if it doesn't exist.
+ * @param actions - Action tracking object for batch operations. Defaults to empty arrays.
+ *
+ * @returns Promise resolving to the created Connection object
+ *
+ * @example
+ * // Simple usage with concepts
+ * const person = await CreateTheConceptLocal('Alice', 'the_person', 101, 1, 1, 2);
+ * const email = await CreateTheConceptLocal('alice@example.com', 'the_email', 101, 1, 2, 2);
+ *
+ * const connection = await CreateConnection(person, email, 'the_person_email');
+ * // Connection created with:
+ * // - ofTheConceptId: person.id
+ * // - toTheConceptId: email.id
+ * // - typeId: auto-generated from 'the_person_email'
+ * // - orderId: 1000 (external connection)
+ *
+ * @example
+ * // With action tracking
+ * const actions = { concepts: [], connections: [] };
+ * const conn1 = await CreateConnection(concept1, concept2, 'links_to', actions);
+ * const conn2 = await CreateConnection(concept2, concept3, 'links_to', actions);
+ * console.log(actions.connections.length); // 2
+ *
+ * @see {@link CreateTheConnectionLocal} for the underlying implementation
+ * @see {@link MakeTheTypeConceptLocal} for type concept creation
+ */
+export declare function CreateConnection(ofTheConcept: Concept, toTheConcept: Concept, connectionTypeString: string, actions?: InnerActions): Promise<any>;

package/dist/types/Services/Local/DeleteConceptLocal.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Deletes a concept from local storage (IndexedDB).
+ *
+ * This function removes a concept from LocalConceptsData, effectively deleting it
+ * from the local IndexedDB cache. This is a local-only delete - it does NOT sync
+ * the deletion to the backend.
+ *
+ * **Important Notes:**
+ * - Only deletes from local storage (IndexedDB)
+ * - Does NOT delete from backend server
+ * - Does NOT automatically delete related connections
+ * - For full deletion including backend, use DeleteConceptById
+ * - Works with both negative (local) and positive (synced) IDs
+ *
+ * **Use Cases:**
+ * - Cleaning up local draft concepts
+ * - Removing concepts before they're synced
+ * - Local cache management
+ * - Testing and development
+ *
+ * **Process:**
+ * 1. Fetches the concept via GetTheConceptLocal
+ * 2. Removes it from LocalConceptsData
+ * 3. Updates IndexedDB
+ *
+ * @param id - The concept ID to delete (negative for local, positive for synced)
+ *
+ * @returns Promise that resolves when deletion is complete
+ *
+ * @example
+ * // Delete a local concept
+ * await DeleteConceptLocal(-12345);
+ * console.log("Local concept deleted");
+ *
+ * @example
+ * // Delete after checking existence
+ * const concept = await GetTheConceptLocal(-67890);
+ * if (concept.id !== 0) {
+ *   await DeleteConceptLocal(concept.id);
+ *   console.log("Deleted:", concept.characterValue);
+ * }
+ *
+ * @see {@link DeleteConceptById} for full deletion including backend
+ * @see {@link GetTheConceptLocal} for retrieving concepts before deletion
+ * @see {@link LocalConceptsData.RemoveConcept} for the underlying removal operation
+ */
+export declare function DeleteConceptLocal(id: number): Promise<any>;

package/dist/types/Services/Local/GetCompositionListLocal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Retrieves all compositions of a specific type from local storage.
+ *
+ * **Process Flow**:
+ * 1. Finds the type concept by compositionName (e.g., "the_project")
+ * 2. Queries all concepts with that typeId belonging to the user
+ * 3. Fetches full composition for each concept
+ * 4. Returns array of complete compositions
+ *
+ * @param compositionName - The type name of compositions to retrieve (e.g., "the_project", "the_person")
+ * @param userId - User ID to filter compositions by ownership
+ * @returns Array of composition objects (empty array if type not found)
+ * @throws Error if lookup or composition fetching fails
+ *
+ * @example
+ * // Get all local projects for a user
+ * const projects = await GetCompositionListLocal("the_project", 101);
+ * // Returns: [{id: -1, data: {...}}, {id: -2, data: {...}}]
+ */
+export declare function GetCompositionListLocal(compositionName: string, userId: number): Promise<any>;
+/**
+ * Retrieves all compositions of a specific type with DATAID format (includes concept ID).
+ *
+ * Same as GetCompositionListLocal but returns compositions in data-id wrapper format,
+ * which includes both the composition data and its concept ID for easier reference.
+ *
+ * @param compositionName - The type name of compositions to retrieve
+ * @param userId - User ID to filter compositions by ownership
+ * @returns Array of composition objects in {id, data} format
+ * @throws Error if lookup or composition fetching fails
+ *
+ * @example
+ * // Get all local projects with IDs
+ * const projects = await GetCompositionListLocalWithId("the_project", 101);
+ * // Returns: [{id: -1, data: {the_name: "Project A"}}, {id: -2, data: {...}}]
+ */
+export declare function GetCompositionListLocalWithId(compositionName: string, userId: number): Promise<any>;

package/dist/types/Services/Local/GetCompositionLocal.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Retrieves a complete composition structure from local storage (IndexedDB).
+ *
+ * This function fetches a composition using local-only data, building a hierarchical
+ * structure from local connections and concepts. If the concept has been synced to the
+ * backend, it can automatically fall back to fetching from the server.
+ *
+ * **Process:**
+ * 1. Fetches all local connections for the composition
+ * 2. Identifies all connected concept IDs
+ * 3. Retrieves the main concept from LocalConceptsData
+ * 4. If concept not found locally, checks if it's been synced (TranslateLocalToReal)
+ * 5. Falls back to server GetComposition if concept is synced
+ * 6. Recursively builds composition tree from local data
+ * 7. Organizes output by concept type
+ *
+ * **Local vs Server:**
+ * - Prioritizes local data (IndexedDB)
+ * - Automatic fallback to server if concept synced
+ * - Uses LocalConnectionData for connections
+ * - Uses LocalConceptsData for concepts
+ *
+ * **Output Format (JUSTDATA):**
+ * Returns an object keyed by the main concept's type:
+ * ```
+ * {
+ *   "Person": {
+ *     name: "Alice",
+ *     email: {...},
+ *     projects: {...}
+ *   }
+ * }
+ * ```
+ *
+ * @param id - The concept ID (can be negative for local or positive for synced)
+ *
+ * @returns Promise resolving to composition data organized by concept type
+ *
+ * @example
+ * // Get local composition
+ * const localComp = await GetCompositionLocal(-12345);
+ * console.log(localComp["Project"]);
+ * // Returns all data connected to this local project
+ *
+ * @example
+ * // Get synced concept (automatically falls back to server)
+ * const syncedComp = await GetCompositionLocal(-67890);
+ * // If concept synced to server, fetches from there
+ *
+ * @throws Re-throws errors for handling by caller
+ *
+ * @see {@link GetCompositionLocalWithId} for composition with ID and data wrapper
+ * @see {@link GetComposition} for server-only composition retrieval
+ * @see {@link recursiveFetchLocal} for the recursive building logic
+ */
+export declare function GetCompositionLocal(id: number): Promise<any>;
+/**
+ * Retrieves a local composition with ID and data wrapper (DATAID format).
+ *
+ * This is a variant of GetCompositionLocal that returns the composition data
+ * wrapped in an object that includes both the data and the concept ID. This format
+ * is useful for tracking which concept the data belongs to.
+ *
+ * **Output Format (DATAID):**
+ * ```
+ * {
+ *   data: {
+ *     "Person": {
+ *       name: "Alice",
+ *       email: {...}
+ *     }
+ *   },
+ *   id: 12345
+ * }
+ * ```
+ *
+ * **Differences from GetCompositionLocal:**
+ * - Returns { data, id } wrapper object
+ * - Same local data retrieval process
+ * - Same recursive building logic
+ * - No automatic server fallback
+ *
+ * @param id - The concept ID (negative for local, positive for synced)
+ *
+ * @returns Promise resolving to object with { data, id } structure
+ *
+ * @example
+ * const result = await GetCompositionLocalWithId(-12345);
+ * console.log(result.id);           // -12345
+ * console.log(result.data.Project); // Composition data
+ *
+ * @throws Re-throws errors for handling by caller
+ *
+ * @see {@link GetCompositionLocal} for standard format without ID wrapper
+ * @see {@link GetCompositionWithId} for server version
+ */
+export declare function GetCompositionLocalWithId(id: number): Promise<any>;

package/dist/types/Services/Local/GetConceptByCharacterLocal.d.ts

@@ -0,0 +1,56 @@
+import { Concept } from "../../app";
+/**
+ * Retrieves a local concept by character value with typeId=51 (standard type).
+ *
+ * Simple lookup in LocalConceptsData for concepts matching the character value
+ * and having typeId of 51.
+ *
+ * @param characterValue - The character value to search for
+ * @returns Concept matching the character and type, or empty concept if not found
+ */
+export default function GetConceptByCharacterLocal(characterValue: string): Promise<Concept>;
+/**
+ * Retrieves a local concept by character value, handling hierarchical type names.
+ *
+ * **Complex Logic**: For compound names (e.g., "the_person_email"):
+ * 1. Splits string by underscore
+ * 2. Recursively processes first part to get category ID
+ * 3. Searches using character value and derived category
+ * 4. Falls back to simple character search for single words
+ *
+ * **Special Case**: Returns concept with id=1 for character value "the".
+ *
+ * @param character - The character value to find (e.g., "the_status", "the_person_email")
+ * @returns Concept associated with the character value
+ *
+ * @example
+ * const concept = await GetConceptByCharacterAndCategoryLocal("the_person_email");
+ * // Splits into "the_person" (category) and searches with that context
+ */
+export declare function GetConceptByCharacterAndCategoryLocal(character: string): Promise<any>;
+/**
+ * Retrieves a concept by character value and category ID from local memory.
+ *
+ * Direct lookup in LocalConceptsData without server fallback.
+ *
+ * @param value - The character value to search for
+ * @param categoryId - The category ID to filter by
+ * @returns Concept matching the character and category, or empty concept if not found
+ */
+export declare function GetConceptByCategoryAndCharacterLocalMemory(value: string, categoryId: number): Promise<Concept>;
+/**
+ * Retrieves a concept by character value with automatic server fallback.
+ *
+ * **Complex Logic**:
+ * 1. First checks LocalConceptsData for existing concept
+ * 2. If not found (id==0 or null), fetches from server via GetLocalConceptByCharacterValue
+ * 3. After server fetch, rechecks LocalConceptsData (now populated)
+ * 4. Returns the concept or throws error
+ *
+ * Use this when you need guaranteed concept retrieval with server sync.
+ *
+ * @param characterValue - The character value to search for
+ * @returns Concept from local storage, fetching from server if needed
+ * @throws Error if server fetch fails
+ */
+export declare function GetConceptByCharacterLocalFull(characterValue: string): Promise<Concept>;

package/dist/types/Services/Local/GetConnectionOfTheConceptLocal.d.ts

@@ -0,0 +1,19 @@
+import { Connection } from "../../app";
+/**
+ * Retrieves all connections originating from a specific concept with a given type.
+ *
+ * Searches local storage (IndexedDB) for connections where:
+ * - ofTheConceptId matches the provided concept ID
+ * - typeId matches the provided type
+ *
+ * @param ofTheConcept - The source concept ID (connections originating from this concept)
+ * @param typeId - The connection type ID to filter by
+ * @param userId - User ID (currently not used in filtering)
+ * @returns Array of Connection objects matching the criteria (empty array if none found)
+ * @throws Error if local storage query fails
+ *
+ * @example
+ * // Get all "has_property" connections from a person concept
+ * const connections = await GetConnectionOfTheConceptLocal(personId, 42, userId);
+ */
+export declare function GetConnectionOfTheConceptLocal(ofTheConcept: number, typeId: number, userId: number): Promise<Connection[]>;

package/dist/types/Services/Local/GetRelationLocal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Retrieves all related compositions from local storage by relation name.
+ *
+ * **Process Flow (Complex Logic)**:
+ * 1. Converts relation string to type concept (e.g., "the_email" → type concept)
+ * 2. Finds all connections from source concept with that relation type
+ * 3. For each connection, retrieves the target composition
+ * 4. Returns array of all related compositions
+ *
+ * @param id - The source concept ID to get relations from
+ * @param relation - The relation name (e.g., "the_email", "the_address")
+ * @param userId - User ID for permissions
+ * @returns Array of composition objects representing related entities
+ * @throws Error if relation lookup or composition retrieval fails
+ *
+ * @example
+ * // Get all email addresses related to a person
+ * const emails = await GetRelationLocal(personId, "the_email", userId);
+ * // Returns: [emailComposition1, emailComposition2, ...]
+ */
+export declare function GetRelationLocal(id: number, relation: string, userId: number): Promise<any>;

package/dist/types/Services/Local/GetTheConceptLocal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Retrieves a concept by ID with support for both local (virtual) and server concepts.
+ *
+ * This is the primary function for fetching concepts in offline/local mode. It intelligently
+ * handles three types of concept IDs and retrieves from appropriate sources:
+ *
+ * **ID Types Handled:**
+ * 1. **Negative IDs (Virtual/Local)**: Concepts created locally not yet synced
+ *    - Stored in LocalConceptsData (IndexedDB)
+ *    - Return negative IDs
+ *
+ * 2. **Synced Virtual IDs**: Originally local concepts now synced to backend
+ *    - Looked up via LocalGhostIdTree (maps negative to positive IDs)
+ *    - Returns positive (real) ID with ghostId reference
+ *
+ * 3. **Positive IDs (Server)**: Real backend concepts
+ *    - Fetched via GetTheConcept from backend
+ *    - Converted to LConcept format
+ *    - May have undefined ghostId
+ *
+ * **Retrieval Strategy:**
+ * - If id < 0: Check LocalConceptsData → Check LocalGhostIdTree
+ * - If id >= 0: Fetch from backend → Convert to LConcept
+ * - Routes through service worker if enabled
+ * - Returns default empty concept if not found
+ *
+ * **Ghost ID System:**
+ * - ghostId: Original negative ID (preserved after sync)
+ * - id: Current ID (negative if local, positive if synced)
+ * - LocalGhostIdTree maintains the mapping
+ *
+ * @param id - The concept ID to retrieve. Can be:
+ *            - Negative (e.g., -12345) for local-only concepts
+ *            - Positive (e.g., 789) for server concepts
+ *
+ * @returns Promise resolving to a Concept object in LConcept format.
+ *         Returns default concept (id=0) if not found.
+ *
+ * @example
+ * // Get a local concept (negative ID)
+ * const localConcept = await GetTheConceptLocal(-12345);
+ * console.log(localConcept.id); // -12345
+ * console.log(localConcept.characterValue); // "Draft Note"
+ *
+ * @example
+ * // Get a synced concept (originally local, now on server)
+ * const syncedConcept = await GetTheConceptLocal(-12345);
+ * console.log(syncedConcept.id); // 789 (now positive, synced)
+ * console.log(syncedConcept.ghostId); // -12345 (original ID preserved)
+ *
+ * @example
+ * // Get a server concept
+ * const serverConcept = await GetTheConceptLocal(456);
+ * console.log(serverConcept.id); // 456
+ * // Converted to LConcept format for consistency
+ *
+ * @throws Logs errors but returns default concept instead of throwing
+ *
+ * @see {@link CreateTheConceptLocal} for creating local concepts
+ * @see {@link GetTheConcept} for fetching server concepts only
+ * @see {@link convertFromConceptToLConcept} for format conversion
+ */
+export declare function GetTheConceptLocal(id: number): Promise<any>;

package/dist/types/Services/Local/MakeTheConceptLocal.d.ts

@@ -0,0 +1,22 @@
+import { InnerActions } from "../../app";
+/**
+ * Gets or creates a local concept - implements get-or-create pattern.
+ *
+ * Checks LocalConceptsData for existing concept matching referent and typeId.
+ * If found, returns existing concept. If not found, creates new local concept.
+ *
+ * **Special Case**: If typeCharacter is "the", sets categoryId to 1 (system category).
+ *
+ * @param referent - The character value/name of the concept
+ * @param typeCharacter - Type name string (e.g., "the_name")
+ * @param userId - User ID creating the concept
+ * @param categoryId - Category classification ID
+ * @param typeId - Type classification ID
+ * @param actions - Action tracking for batch operations
+ * @returns Existing or newly created Concept
+ *
+ * @example
+ * const concept = await MakeTheConceptLocal("Active", "the_status", 101, 1, 5);
+ * // Returns existing "Active" status or creates new one
+ */
+export default function MakeTheConceptLocal(referent: string, typeCharacter: string, userId: number, categoryId: number, typeId: number, actions?: InnerActions): Promise<any>;

package/dist/types/Services/Local/MakeTheInstanceConceptLocal.d.ts

@@ -0,0 +1,164 @@
+import { InnerActions } from "../../Constants/general.const";
+/**
+ * Creates or retrieves an instance concept locally - the core building block of the concept-connection system.
+ *
+ * This is THE fundamental function for creating concepts in local storage. It implements an intelligent
+ * get-or-create pattern that checks for existing concepts before creating new ones, preventing duplicates
+ * while supporting both unique instances and composition concepts.
+ *
+ * **Core Behaviors:**
+ * 1. **Composition Mode (composition=true)**: Always creates a new concept
+ *    - Used for containers/objects that need unique instances
+ *    - Marks concept with isComposition flag
+ *    - Example: Each "Project" is unique, even with same name
+ *
+ * 2. **Instance Mode (composition=false)**: Get-or-create pattern
+ *    - Checks if concept with same type and value exists
+ *    - Returns existing if found (deduplication)
+ *    - Creates new only if not found
+ *    - Example: "Published" status concept reused across items
+ *
+ * 3. **Long Text Handling**: Values >255 characters always create new
+ *    - Prevents expensive lookups on large text
+ *    - Each long text gets unique concept
+ *
+ * **Type String Processing:**
+ * - **Best Practice**: Always pass type with "the_" prefix (e.g., "the_name", "the_email")
+ * - Auto-correction: If missing, "the_" is automatically added internally
+ *   - "name" → "the_name" (auto-corrected)
+ *   - "email" → "the_email" (auto-corrected)
+ *   - "the_status" → "the_status" (already correct)
+ * - Creates type concept if it doesn't exist
+ * - **Recommendation**: Use explicit "the_" prefix for code clarity and consistency
+ *
+ * **Sync and Storage:**
+ * - Adds concept to LocalSyncData queue for backend sync
+ * - Stores in LocalConceptsData (IndexedDB)
+ * - Tracks in actions parameter for batch operations
+ * - Assigns negative ID (virtual/local)
+ *
+ * **Process Flow:**
+ * 1. Normalizes type string (adds "the_" prefix)
+ * 2. Creates/retrieves type concept via MakeTheTypeConceptLocal
+ * 3. If composition=true: Creates new concept immediately
+ * 4. If referent length >255: Creates new concept
+ * 5. If regular instance: Checks for existing by type+value
+ * 6. Returns existing or creates new
+ * 7. Attaches type information
+ * 8. Adds to sync queue
+ *
+ * @param type - The type/key of the concept. **Should follow the format "the_xyz"**.
+ *              Represents what kind of data this is.
+ *              Examples: "the_name", "the_email", "the_status", "the_first_name"
+ *
+ *              **Note**: If you pass without "the_" prefix (e.g., "name"), the code will
+ *              automatically add it internally (becomes "the_name"). However, best practice
+ *              is to always include the "the_" prefix for clarity and consistency.
+ *
+ * @param referent - The actual value/content of the concept.
+ *                  The human-readable data (e.g., "Alice", "alice@example.com", "Active").
+ *                  Can be empty string for composition concepts.
+ *
+ * @param composition - Boolean flag determining creation behavior.
+ *                     - true: Always creates new concept (unique instances)
+ *                     - false: Get-or-create pattern (reuses existing)
+ *                     Defaults to false.
+ *
+ * @param userId - The ID of the user creating this concept. Used for ownership and permissions.
+ *
+ * @param accessId - Access control level. Typically 4 (default internal access).
+ *                  Controls who can view/modify this concept.
+ *
+ * @param sessionInformationId - Session identifier for tracking. Defaults to 999 (system).
+ *                              Used for audit logging and session management.
+ *
+ * @param referentId - Optional reference to another concept ID.
+ *                    Used when this concept is an instance of or refers to another concept.
+ *                    Defaults to 0 (no reference).
+ *
+ * @param actions - Action tracking object that accumulates all created concepts and connections.
+ *                 Used for batch operations, rollback, and sync management.
+ *                 Structure: { concepts: Concept[], connections: Connection[] }
+ *
+ * @returns Promise resolving to the created or retrieved Concept object with:
+ *         - Negative ID if newly created locally
+ *         - Attached type information (concept.type)
+ *         - All standard concept properties
+ *
+ * @example
+ * // Create a reusable status concept (get-or-create)
+ * const status = await MakeTheInstanceConceptLocal(
+ *   "the_status",       // type (with "the_" prefix - best practice)
+ *   "Active",           // value
+ *   false,              // not composition - will reuse if exists
+ *   101,                // userId
+ *   4,                  // accessId
+ *   999,                // sessionId
+ *   0                   // no referent
+ * );
+ * // First call creates, subsequent calls return same concept
+ *
+ * @example
+ * // Create a composition concept (always new)
+ * const project = await MakeTheInstanceConceptLocal(
+ *   "the_project",      // type (with "the_" prefix)
+ *   "Project Alpha",    // value
+ *   true,               // composition - always creates new
+ *   101,
+ *   4,
+ *   999,
+ *   0
+ * );
+ * // Each project is unique, even with same name
+ * console.log(project.isComposition); // true
+ *
+ * @example
+ * // Type prefix is added automatically if missing (but prefer explicit)
+ * const email = await MakeTheInstanceConceptLocal(
+ *   "email",            // Missing "the_" - will become "the_email" internally
+ *   "alice@example.com",
+ *   false,
+ *   101, 4
+ * );
+ * console.log(email.typeCharacter); // "the_email" (auto-prefixed)
+ *
+ * // RECOMMENDED: Always include "the_" prefix explicitly
+ * const emailBetter = await MakeTheInstanceConceptLocal(
+ *   "the_email",        // Explicit prefix - clearer and more consistent
+ *   "bob@example.com",
+ *   false,
+ *   101, 4
+ * );
+ *
+ * @example
+ * // Long text always creates new concept
+ * const longDescription = "Lorem ipsum...".repeat(100); // >255 chars
+ * const concept = await MakeTheInstanceConceptLocal(
+ *   "the_description",  // type with "the_" prefix
+ *   longDescription,
+ *   false,              // Even with false, creates new due to length
+ *   101, 4
+ * );
+ *
+ * @example
+ * // Track actions for batch operations
+ * const actions = { concepts: [], connections: [] };
+ * await MakeTheInstanceConceptLocal("the_name", "Alice", false, 101, 4, 999, 0, actions);
+ * await MakeTheInstanceConceptLocal("the_email", "alice@ex.com", false, 101, 4, 999, 0, actions);
+ * console.log(actions.concepts.length); // 2 (plus any type concepts created)
+ *
+ * @example
+ * // Deduplication in action
+ * const status1 = await MakeTheInstanceConceptLocal("the_status", "Published", false, 101, 4);
+ * const status2 = await MakeTheInstanceConceptLocal("the_status", "Published", false, 101, 4);
+ * console.log(status1.id === status2.id); // true - same concept reused
+ *
+ * @throws Logs errors and re-throws for handling by caller.
+ *        Common issues: Type concept creation failures, IndexedDB errors.
+ *
+ * @see {@link CreateTheConceptLocal} for the underlying creation function
+ * @see {@link MakeTheTypeConceptLocal} for type concept creation/retrieval
+ * @see {@link LocalConceptsData.GetConceptByCharacterAndTypeLocal} for existence check
+ * @see {@link LocalSyncData.AddConcept} for sync queue management
+ */
+export declare function MakeTheInstanceConceptLocal(type: string, referent: string, composition: boolean | undefined, userId: number, accessId: number, sessionInformationId?: number, referentId?: number, actions?: InnerActions): Promise<any>;