@ibgib/web-gib 0.0.11 → 0.0.13

package/src/agent-texts/projects-agent-texts.mts

@@ -1,17 +1,17 @@
-import { AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF, AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS } from "./common-agent-texts.mjs";
+// import { AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF, AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS } from "./common-agent-texts.mjs";
 
-export const AGENT_GOAL_PROJECTSAGENT = [
-    `In general, your goal is just to do your best to parse the chat texts and choose the best course of action in terms of one or more functions. Please refer to those available function schemas and descriptions.`,
-    `Usually, you will want to talk with them via the tell user function.`,
-    `As a projects manager agent, you are responsible for CRUD project ibgibs. In ibgib, "project" is basically a focus of effort. You can have a project like conventional projects in code, but because of the granular version-control-like power of ibgib, you can consider a sub-component of a project itself to be a project. This is th conventional progress of work: you work on some "thing", then when it gets large enough, you break it apart into sub-"things". A "project" is this idea of a "thing", but really it's an "ibgib". But people don't know what that means. `,
-    `But concretely, at this stage in development, I'm not quite sure what projects will entail as far implementation goes. Your job though will be to do management of them, e.g., creating projects, inter-project actions like copying/importing ibgibs, etc.`,
-].join('\n');
+// export const AGENT_GOAL_PROJECTSAGENT = [
+//     `In general, your goal is just to do your best to parse the chat texts and choose the best course of action in terms of one or more functions. Please refer to those available function schemas and descriptions.`,
+//     `Usually, you will want to talk with them via the tell user function.`,
+//     `As a projects manager agent, you are responsible for CRUD project ibgibs. In ibgib, "project" is basically a focus of effort. You can have a project like conventional projects in code, but because of the granular version-control-like power of ibgib, you can consider a sub-component of a project itself to be a project. This is th conventional progress of work: you work on some "thing", then when it gets large enough, you break it apart into sub-"things". A "project" is this idea of a "thing", but really it's an "ibgib". But people don't know what that means. `,
+//     `But concretely, at this stage in development, I'm not quite sure what projects will entail as far implementation goes. Your job though will be to do management of them, e.g., creating projects, inter-project actions like copying/importing ibgibs, etc.`,
+// ].join('\n');
 
-export const AGENT_INITIAL_SYSTEM_TEXT_PROJECTSAGENT = [
-    AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS,
-    AGENT_GOAL_PROJECTSAGENT,
-].join('\n');
+// export const AGENT_INITIAL_SYSTEM_TEXT_PROJECTSAGENT = [
+//     AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS,
+//     AGENT_GOAL_PROJECTSAGENT,
+// ].join('\n');
 
-export const AGENT_INITIAL_CHAT_TEXT_PROJECTSAGENT = [
-    AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF,
-].join('\n')
+// export const AGENT_INITIAL_CHAT_TEXT_PROJECTSAGENT = [
+//     AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF,
+// ].join('\n')

package/src/agent-texts/raw-agent-texts.mts

@@ -1,18 +1,18 @@
-import { AGENT_GOAL_COMMON, AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF, AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS, AGENT_WEBSITE_DESCRIPTION } from "./common-agent-texts.mjs";
+// import { AGENT_GOAL_COMMON, AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF, AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS, AGENT_WEBSITE_DESCRIPTION } from "./common-agent-texts.mjs";
 
-export const AGENT_GOAL_RAWAGENT = [
-    AGENT_GOAL_COMMON,
-    `You yourself are a "raw component" agent. This component just shows the user the raw details of an ibgib. Your job is to provide information guidance for this ibgib. In the future, you may be equipped with tools to edit the ibgib, but for now the ibgib is readonly.`,
-].join('\n');
+// export const AGENT_GOAL_RAWAGENT = [
+//     AGENT_GOAL_COMMON,
+//     `You yourself are a "raw component" agent. This component just shows the user the raw details of an ibgib. Your job is to provide information guidance for this ibgib. In the future, you may be equipped with tools to edit the ibgib, but for now the ibgib is readonly.`,
+// ].join('\n');
 
-export const AGENT_INITIAL_SYSTEM_TEXT_RAWAGENT = [
-    AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS,
-    AGENT_GOAL_RAWAGENT,
-    AGENT_WEBSITE_DESCRIPTION,
-    `Now, that's just to give you info on the website. Your job is not primarily to answer questions about the website. Your primary job is dealing with the ibgib being presented to the user. This includes answering any questions regarding the ibgib's various fields.`,
-    `Currently, the raw view that the user sees will be in the center panel as one of a project's child tabs. So say a user is editing a child ibgib as if it is like a text document. It is possible they want to see the internal details of the ibgib for some reason. So they open the raw viewer.`,
-    `This will also be a backup viewer in case there is some error, but this is not the primary use case.`,
-].join('\n');
-export const AGENT_INITIAL_CHAT_TEXT_RAWAGENT = [
-    AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF,
-].join('\n');
+// export const AGENT_INITIAL_SYSTEM_TEXT_RAWAGENT = [
+//     AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS,
+//     AGENT_GOAL_RAWAGENT,
+//     AGENT_WEBSITE_DESCRIPTION,
+//     `Now, that's just to give you info on the website. Your job is not primarily to answer questions about the website. Your primary job is dealing with the ibgib being presented to the user. This includes answering any questions regarding the ibgib's various fields.`,
+//     `Currently, the raw view that the user sees will be in the center panel as one of a project's child tabs. So say a user is editing a child ibgib as if it is like a text document. It is possible they want to see the internal details of the ibgib for some reason. So they open the raw viewer.`,
+//     `This will also be a backup viewer in case there is some error, but this is not the primary use case.`,
+// ].join('\n');
+// export const AGENT_INITIAL_CHAT_TEXT_RAWAGENT = [
+//     AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF,
+// ].join('\n');

package/src/agent-texts/text-editor-agent-texts.mts

@@ -1,20 +1,20 @@
-import { AGENT_GOAL_COMMON, AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF, AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS, AGENT_WEBSITE_DESCRIPTION } from "./common-agent-texts.mjs";
+// import { AGENT_GOAL_COMMON, AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF, AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS, AGENT_WEBSITE_DESCRIPTION } from "./common-agent-texts.mjs";
 
-export const AGENT_SPECIAL_IBGIB_TYPE_TEXTEDITORAGENT = 'texteditoragent';
-export const AGENT_GOAL_TEXTEDITORAGENT = [
-    AGENT_GOAL_COMMON,
-    `You yourself are a "text editor component" agent. This component simply enables editing of text somewhere in an ibgib. Your job is to provide information guidance for this ibgib.`,
-].join('\n');
+// export const AGENT_SPECIAL_IBGIB_TYPE_TEXTEDITORAGENT = 'texteditoragent';
+// export const AGENT_GOAL_TEXTEDITORAGENT = [
+//     AGENT_GOAL_COMMON,
+//     `You yourself are a "text editor component" agent. This component simply enables editing of text somewhere in an ibgib. Your job is to provide information guidance for this ibgib.`,
+// ].join('\n');
 
-export const AGENT_INITIAL_SYSTEM_TEXT_TEXTEDITORAGENT = [
-    AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS,
-    AGENT_GOAL_TEXTEDITORAGENT,
-    AGENT_WEBSITE_DESCRIPTION,
-    `Now, that's just to give you info on the website. Your job is not primarily to answer questions about the website. Your primary job is dealing with the ibgib being presented to the user. This includes answering any questions regarding the ibgib's various fields.`,
-    `Currently, the text editor view that the user sees will be in the center panel as one of a project's child tabs. So say a user is editing a child ibgib as if it is like a text document. It is possible they want to see the internal details of the ibgib for some reason. So they open the text editor viewer.`,
-    `This will also be a backup viewer in case there is some error, but this is not the primary use case.`,
-].join('\n');
-export const AGENT_INITIAL_CHAT_TEXT_TEXTEDITORAGENT = [
-    AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF,
-].join('\n');
-export const CHAT_WITH_AGENT_PLACEHOLDER_TEXTEDITORAGENT = '';
+// export const AGENT_INITIAL_SYSTEM_TEXT_TEXTEDITORAGENT = [
+//     AGENT_SYSTEM_PROMPT_COMMON_INSTRUCTIONS,
+//     AGENT_GOAL_TEXTEDITORAGENT,
+//     AGENT_WEBSITE_DESCRIPTION,
+//     `Now, that's just to give you info on the website. Your job is not primarily to answer questions about the website. Your primary job is dealing with the ibgib being presented to the user. This includes answering any questions regarding the ibgib's various fields.`,
+//     `Currently, the text editor view that the user sees will be in the center panel as one of a project's child tabs. So say a user is editing a child ibgib as if it is like a text document. It is possible they want to see the internal details of the ibgib for some reason. So they open the text editor viewer.`,
+//     `This will also be a backup viewer in case there is some error, but this is not the primary use case.`,
+// ].join('\n');
+// export const AGENT_INITIAL_CHAT_TEXT_TEXTEDITORAGENT = [
+//     AGENT_INITIAL_CHAT_HI_PLEASEINTRO_YOURSELF,
+// ].join('\n');
+// export const CHAT_WITH_AGENT_PLACEHOLDER_TEXTEDITORAGENT = '';

package/src/common/project/project-constants.mts

@@ -81,3 +81,5 @@ export const AGENT_AVAILABLE_FUNCTIONS_PROJECTCHILDTEXTAGENT: APIFunctionInfo<an
 //         AGENT_AVAILABLE_FUNCTIONS_PROJECTCHILDTEXTAGENT.push(x);
 //     }); // hasn't initialized yet
 // });
+
+export const AGENT_SPECIAL_IBGIB_TYPE_PROJECTAGENT = 'projectagent';

package/src/common/project/project-helper.mts

@@ -18,13 +18,12 @@ import { GLOBAL_LOG_A_LOT } from '../../constants.mjs';
 import {
     PROJECT_ATOM, PROJECT_DESC_REGEXP, PROJECT_NAME_REGEXP,
     DEFAULT_PROJECT_SAFE_NAME_LENGTH, DEFAULT_PROJECT_ADDL_METADATA_LENGTH,
-    PROJECT_CHILD_DEFAULT_REL8N_NAME,
-} from './project-constants.mjs'; // Constants file to be created
+    PROJECT_CHILD_DEFAULT_REL8N_NAME, AGENT_SPECIAL_IBGIB_TYPE_PROJECTAGENT,
+} from './project-constants.mjs';
 import {
     ProjectData_V1, ProjectIbGib_V1, ProjectIbInfo, ProjectAddlMetadataInfo,
 } from './project-types.mjs';
 import { getAgentsSvc } from '../../witness/agent/agents-service-v1.mjs';
-import { AGENT_SPECIAL_IBGIB_TYPE_PROJECTAGENT } from '../../agent-texts/project-agent-texts.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 

package/src/keystone/keystone-config-builder.mts

@@ -0,0 +1,186 @@
+import {
+    KeystonePoolConfig,
+    KeystonePoolConfig_HashV1,
+    KeystonePoolBehavior,
+    KeystoneReplenishStrategy,
+    KeystonePoolConfigBase
+} from './keystone-types.mjs';
+import { POOL_ID_DEFAULT, POOL_ID_REVOKE, VERB_REVOKE } from './keystone-constants.mjs';
+
+/**
+ * Abstract Base Builder.
+ * Handles configuration common to ALL strategies (Salt, Size, Replenishment, Selection).
+ *
+ * @template TConfig The concrete config type being built.
+ */
+export abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConfigBase> {
+    protected _salt: string = 'default';
+    protected _size: number = 100;
+    protected _replenish: KeystoneReplenishStrategy = 'top-up';
+    protected _seq: number = 0;
+    protected _rand: number = 0;
+    protected _verbs: string[] = [];
+    protected _targetBinding: number = 0; // Default 0
+
+
+    /**
+     * Sets the unique salt/ID for this pool.
+     */
+    withSalt(salt: string): this {
+        this._salt = salt;
+        return this;
+    }
+
+    /**
+     * Sets the total number of challenges to maintain in the pool.
+     */
+    withSize(size: number): this {
+        this._size = size;
+        return this;
+    }
+
+    /**
+    * Binds challenge selection to the content address of the target.
+    * @param chars Number of hex characters to match (e.g. 4).
+    */
+    withTargetBinding(chars: number): this {
+        this._targetBinding = chars;
+        return this;
+    }
+
+    /**
+     * Configures the pool to use strictly Sequential (FIFO) selection.
+     * @param count Number of challenges to consume per sign.
+     */
+    withFIFO(count: number): this {
+        this._seq = count;
+        this._rand = 0;
+        return this;
+    }
+
+    /**
+     * Configures the pool to use strictly Random selection.
+     * @param count Number of challenges to consume per sign.
+     */
+    withRandom(count: number): this {
+        this._seq = 0;
+        this._rand = count;
+        return this;
+    }
+
+    /**
+     * Configures the pool to use Hybrid (Both FIFO and Random) selection.
+     */
+    withHybrid(seqCount: number, randCount: number): this {
+        this._seq = seqCount;
+        this._rand = randCount;
+        return this;
+    }
+
+    /**
+     * Sets the replenishment strategy.
+     */
+    withReplenishStrategy(strategy: KeystoneReplenishStrategy): this {
+        this._replenish = strategy;
+        return this;
+    }
+
+    /**
+     * Constructs the behavioral config object.
+     * Helper for subclasses.
+     */
+    protected buildBehavior(): KeystonePoolBehavior {
+        return {
+            size: this._size,
+            replenish: this._replenish,
+            selectSequentially: this._seq,
+            selectRandomly: this._rand,
+            targetBindingChars: this._targetBinding,
+        };
+    }
+
+    /**
+     * Restricts this pool to specific verbs.
+     * @param verbs List of verb addresses (e.g. 'revoke^gib')
+     */
+    forVerbs(verbs: string[]): this {
+        this._verbs = verbs;
+        return this;
+    }
+
+    protected buildBase(): KeystonePoolConfigBase {
+        // Helper to keep the concrete build() clean
+        return {
+            type: 'hash-reveal-v1', // This is overridden by concrete/interface usually, but needed for base shape
+            salt: this._salt,
+            allowedVerbs: this._verbs
+        } as any;
+    }
+
+    abstract build(): TConfig;
+}
+
+/**
+ * Concrete Builder for Hash-Reveal V1 Strategy.
+ */
+export class KeystoneConfigBuilder_HashV1 extends KeystoneConfigBuilderBase<KeystonePoolConfig_HashV1> {
+    private _algo: 'SHA-256' | 'SHA-512' = 'SHA-256';
+    private _rounds: number = 1;
+
+    /**
+     * Sets the hashing strength.
+     */
+    withHash(algo: 'SHA-256' | 'SHA-512', rounds: number = 1): this {
+        this._algo = algo;
+        this._rounds = rounds;
+        return this;
+    }
+
+    build(): KeystonePoolConfig_HashV1 {
+        return {
+            type: 'hash-reveal-v1',
+            salt: this._salt,
+            allowedVerbs: this._verbs, // <--- Mapped here
+            behavior: this.buildBehavior(),
+            algo: this._algo,
+            rounds: this._rounds,
+        };
+    }
+}
+
+// ===========================================================================
+// STATIC ENTRY POINT (Optional Convenience)
+// ===========================================================================
+
+export class KeystoneConfig {
+    static hash(): KeystoneConfigBuilder_HashV1 {
+        return new KeystoneConfigBuilder_HashV1();
+    }
+
+    // Future:
+    // static pow(): KeystoneConfigBuilder_PoW { ... }
+}
+
+// ===========================================================================
+// FACTORY FUNCTIONS (Presets)
+// ===========================================================================
+
+export function createStandardPoolConfig(salt: string = POOL_ID_DEFAULT): KeystonePoolConfig {
+    return KeystoneConfig.hash()
+        .withSalt(salt)
+        .withSize(100)
+        .withHybrid(2, 2)
+        .withReplenishStrategy('top-up')
+        .build();
+}
+
+export function createRevocationPoolConfig(salt: string = POOL_ID_REVOKE): KeystonePoolConfig {
+    return KeystoneConfig.hash()
+        .withSalt(salt)
+        .withHash('SHA-256', 10)
+        .withSize(500)
+        .withHybrid(10, 10)
+        .withReplenishStrategy(KeystoneReplenishStrategy.scorchedEarth)
+        .forVerbs([VERB_REVOKE])
+        .build();
+}

package/src/keystone/keystone-constants.mts

@@ -0,0 +1,16 @@
+export const KEYSTONE_ATOM = "keystone";
+
+/**
+ * The specific ibGib address for the 'revoke' verb.
+ * Used in Claims to indicate the Keystone should be considered dead.
+ *
+ * NOTE: This is a primitive ibGib address (ib='revoke', gib='gib'),
+ * _but with the `gib` being implied_.
+ */
+export const VERB_REVOKE = "revoke";
+
+/**
+ * Standard pool IDs can be conventionally named after their primary verb.
+ */
+export const POOL_ID_REVOKE = VERB_REVOKE;
+export const POOL_ID_DEFAULT = "default";

package/src/keystone/keystone-helpers.mts

@@ -0,0 +1,207 @@
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { Ib, TransformResult } from "@ibgib/ts-gib/dist/types.mjs";
+import { getIbAndGib } from "@ibgib/ts-gib/dist/helper.mjs";
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../constants.mjs";
+import { KEYSTONE_ATOM } from "./keystone-constants.mjs";
+import { KeystoneData_V1, KeystoneIbGib_V1, KeystoneIbInfo_V1, KeystoneChallengePool } from "./keystone-types.mjs";
+import { getGib } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * space-delimited keystone ib containing select keystone metadata.
+ *
+ * NOTE: This must match {@link parseKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export async function getKeystoneIb({
+    keystoneData,
+}: {
+    keystoneData: KeystoneData_V1,
+}): Promise<Ib> {
+    const lc = `[${getKeystoneIb.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: c3022a146faac9730154f34d1439a225)`); }
+
+        const atom = KEYSTONE_ATOM;
+
+        const ib = [
+            atom,
+        ].join(' ');
+
+        return ib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * NOTE: This must match {@link getKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export async function parseKeystoneIb({
+    ib,
+}: {
+    ib: Ib,
+}): Promise<KeystoneIbInfo_V1> {
+    const lc = `[${parseKeystoneIb.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 73cb6832984255ed48b2f44db6a21e25)`); }
+        const [
+            atom
+        ] = ib.split(' ');
+
+        if (atom !== KEYSTONE_ATOM) {
+            throw new Error(`invalid keystone ib. atom found in ib (${atom}) does not match keystone atom (${KEYSTONE_ATOM}) (E: 79b3d587824c4271b6e60acc76e0c825)`);
+        }
+
+        return {
+            atom,
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+export interface DeterministicResult {
+    /**
+     * The Set of IDs that MUST be present in the solution.
+     * Includes Alice's Demands + Target Binding Matches + FIFO.
+     */
+    mandatoryIds: Set<string>;
+
+    /**
+     * The IDs remaining in the pool that are valid candidates for
+     * the Random/Stochastic step.
+     */
+    availableIds: string[];
+}
+
+/**
+ * The Policy Engine.
+ * Calculates exactly which challenges MUST be consumed based on config and demands.
+ * Enforces STRICT DISTINCTNESS (No double-dipping).
+ */
+export function getDeterministicRequirements({
+    pool,
+    requiredChallengeIds,
+    targetAddr
+}: {
+    pool: KeystoneChallengePool;
+    requiredChallengeIds?: string[];
+    targetAddr?: string;
+}): DeterministicResult {
+    const behavior = pool.config.behavior;
+    const mandatory = new Set<string>();
+
+    // Start with all available IDs.
+    // We assume Object.keys respects insertion order (ES2015+), crucial for FIFO.
+    let available = Object.keys(pool.challenges);
+
+    // ---------------------------------------------------------
+    // 1. Alice's Demands (Explicit Requirements)
+    // ---------------------------------------------------------
+    if (requiredChallengeIds && requiredChallengeIds.length > 0) {
+        for (const id of requiredChallengeIds) {
+            if (!pool.challenges[id]) {
+                throw new Error(`(UNEXPECTED) Required challenge ID not found in pool: ${id} (E: 2c9f8...)`);
+            }
+            // Strict: Consume it.
+            if (!available.includes(id)) {
+                // Should be caught by check above, but handles duplicates in 'demands'
+                continue;
+            }
+            mandatory.add(id);
+        }
+        // Remove from available pool
+        available = available.filter(id => !mandatory.has(id));
+    }
+
+    // ---------------------------------------------------------
+    // 2. Target Binding (Explicit Buckets)
+    // ---------------------------------------------------------
+    if (behavior.targetBindingChars > 0 && targetAddr) {
+        const { gib } = getIbAndGib({ ibGibAddr: targetAddr });
+        if (gib) {
+            // Get required hex prefixes (e.g. 'a', 'b', 'c', '1')
+            const prefixes = gib.substring(0, behavior.targetBindingChars).toLowerCase();
+
+            for (const char of prefixes) {
+                // Look in the Explicit Bucket
+                const bucket = pool.bindingMap[char] || [];
+
+                // Find the first ID in this bucket that is still in 'available'
+                const match = bucket.find(id => available.includes(id));
+
+                if (!match) {
+                    throw new Error(`Entropy Exhaustion. Cannot satisfy binding for char '${char}'. (E: 8d3a1...)`);
+                }
+
+                // Strict: Consume it.
+                mandatory.add(match);
+                available = available.filter(id => id !== match);
+            }
+        }
+    }
+
+    // ---------------------------------------------------------
+    // 3. FIFO (Sequential)
+    // ---------------------------------------------------------
+    if (behavior.selectSequentially > 0) {
+        // Take the first N from the remaining available list
+        if (available.length < behavior.selectSequentially) {
+            throw new Error(`Entropy Exhaustion. Insufficient challenges for FIFO requirement. (E: 9c2b4...)`);
+        }
+
+        const fifoIds = available.slice(0, behavior.selectSequentially);
+        fifoIds.forEach(id => mandatory.add(id));
+
+        // Remove from available
+        available = available.slice(behavior.selectSequentially);
+    }
+
+    return { mandatoryIds: mandatory, availableIds: available };
+}
+
+/**
+ * Helper to update the Binding Map when adding new Challenge IDs.
+ * Uses "Implicit Bucketing" (ID start char) but can be extended for full coverage.
+ */
+export function addToBindingMap(
+    map: { [char: string]: string[] },
+    challengeId: string
+): void {
+    const firstChar = challengeId.charAt(0).toLowerCase();
+    // Validate it is hex
+    if (/[0-9a-f]/.test(firstChar)) {
+        if (!map[firstChar]) map[firstChar] = [];
+        map[firstChar].push(challengeId);
+
+        // OPTIONAL: Implement Full Coverage Strategy here?
+        // e.g. map[challengeId[1]].push(challengeId) ...
+        // For V1, we stick to Native/Implicit bucket (Index 0).
+    }
+}
+
+/**
+ * Helper to clean up Binding Map when removing IDs.
+ */
+export function removeFromBindingMap(
+    map: { [char: string]: string[] },
+    challengeId: string
+): void {
+    // Since we don't know exactly which buckets an ID is in (if we did multi-bucket),
+    // we strictly should scan all. For V1 Native, we check first char.
+    // SAFE IMPLEMENTATION: Scan all buckets.
+    for (const key of Object.keys(map)) {
+        map[key] = map[key].filter(id => id !== challengeId);
+    }
+}