@serfab/cadre-core 0.0.2

package/dist/strand-solicitation.d.ts

@@ -0,0 +1,145 @@
+import type { Libp2p } from '@libp2p/interface';
+import type { OpenInvitation, FormStrandResult, ValidateFormationResult, StrandFormationDisclosure } from './types.js';
+import { type StrandFormationManagerConfig } from './strand-formation-manager.js';
+/**
+ * Interface for validating formation disclosures
+ */
+export interface DisclosureValidator {
+    /**
+     * Validate the disclosure provided by an initiator
+     * @param token The invitation token
+     * @param disclosure The disclosure object from the initiator
+     * @returns Whether the disclosure is acceptable
+     */
+    validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
+}
+/**
+ * Interface for recording formation usage
+ */
+export interface FormationUsageRecorder {
+    /**
+     * Record that a formation invite was used
+     */
+    recordUsage(token: string, initiatorKey: string, strandId: string): Promise<void>;
+    /**
+     * Check if a token has already been used (for single-use invites)
+     */
+    isTokenUsed(token: string): Promise<boolean>;
+    /**
+     * Check if a token is valid and not expired
+     */
+    isTokenValid(token: string): Promise<{
+        valid: boolean;
+        invitation?: OpenInvitation;
+    }>;
+}
+/**
+ * Interface for strand provisioning during formation
+ */
+export interface StrandProvisioner {
+    /**
+     * Provision a new strand after formation is validated
+     */
+    provisionStrand(sAppId: string, initiatorKey: string, responderKey: string): Promise<{
+        strandId: string;
+    }>;
+}
+/**
+ * Interface for signing formation approvals
+ */
+export interface FormationSigner {
+    /**
+     * Sign a formation approval
+     */
+    signFormation(token: string, disclosure: StrandFormationDisclosure): Promise<{
+        validationKey: string;
+        validationSignature: string;
+    }>;
+}
+export interface StrandSolicitationServiceOptions {
+    disclosureValidator?: DisclosureValidator;
+    formationUsageRecorder?: FormationUsageRecorder;
+    strandProvisioner?: StrandProvisioner;
+    formationSigner?: FormationSigner;
+    /** Party ID for this node (used in protocol messages) */
+    partyId?: string;
+    /** Cadre peer addresses for this node */
+    cadrePeerAddrs?: string[];
+    /** Configuration for the formation manager */
+    formationConfig?: StrandFormationManagerConfig;
+}
+/**
+ * Strand Solicitation API for forming strands via open invitations.
+ *
+ * This service handles the high-level API defined in api.md:
+ * - formStrand(invitation, disclosure, node) - called by initiator
+ * - validateStrandFormation(token, disclosure) - called by responder
+ *
+ * When a libp2p node is provided, the underlying protocol is handled by
+ * strand-proto's SessionManager via StrandFormationManager.
+ */
+export declare class StrandSolicitationService {
+    private readonly disclosureValidator?;
+    private readonly formationUsageRecorder?;
+    private readonly strandProvisioner?;
+    private readonly formationSigner?;
+    private readonly partyId;
+    private readonly cadrePeerAddrs;
+    private formationManager?;
+    private readonly formationConfig?;
+    constructor(options?: StrandSolicitationServiceOptions);
+    /**
+     * Get or create the StrandFormationManager.
+     * Lazily initialized to allow configuration after construction.
+     */
+    private getFormationManager;
+    /**
+     * Register as a responder on a libp2p node.
+     * This enables the node to handle incoming strand formation requests.
+     */
+    registerResponder(node: Libp2p): void;
+    /**
+     * Unregister as a responder from a libp2p node.
+     */
+    unregisterResponder(node: Libp2p): void;
+    /**
+     * Form a strand with a responder via an open invitation.
+     *
+     * Called by the initiator (the party who received an out-of-band invitation).
+     * This generates a member key, contacts the responder's cadre, and negotiates
+     * strand formation.
+     *
+     * @param invitation The open invitation (or just token for legacy API)
+     * @param disclosure Identity/context information to share with the responder
+     * @param node Optional libp2p node for real protocol handling
+     * @returns The member key and strand info if successful
+     */
+    formStrand(invitation: OpenInvitation | string, disclosure: StrandFormationDisclosure, node?: Libp2p): Promise<FormStrandResult>;
+    /**
+     * Validate a strand formation request.
+     *
+     * Called by the responder (the party who created the open invitation) when
+     * an initiator contacts them to form a strand. Validates the disclosure
+     * and returns a signed approval.
+     *
+     * @param token The invitation token being used
+     * @param disclosure The disclosure from the initiator
+     * @returns Validation key and signature if approved
+     * @throws If validation fails or token is invalid
+     */
+    validateStrandFormation(token: string, disclosure: StrandFormationDisclosure): Promise<ValidateFormationResult>;
+    /**
+     * Create an open invitation for others to form strands with this party.
+     *
+     * @param sAppId The sApp to use for formed strands
+     * @param expirationMs How long the invitation is valid (ms from now)
+     * @param bootstrap Bootstrap addresses for contacting this party's cadre
+     * @returns The open invitation to share out-of-band
+     */
+    createOpenInvitation(sAppId: string, expirationMs: number, bootstrap: string[]): Promise<OpenInvitation>;
+    /**
+     * Record that a formation was completed successfully.
+     * Called after strand provisioning to track usage.
+     */
+    recordFormationComplete(token: string, initiatorKey: string, strandId: string): Promise<void>;
+}

package/dist/strand-solicitation.js

@@ -0,0 +1,180 @@
+import debug from 'debug';
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { generateKeyPair, privateKeyToProtobuf } from '@libp2p/crypto/keys';
+import { peerIdFromPrivateKey } from '@libp2p/peer-id';
+import { StrandFormationManager } from './strand-formation-manager.js';
+const log = debug('sereus:cadre:solicitation');
+/**
+ * Strand Solicitation API for forming strands via open invitations.
+ *
+ * This service handles the high-level API defined in api.md:
+ * - formStrand(invitation, disclosure, node) - called by initiator
+ * - validateStrandFormation(token, disclosure) - called by responder
+ *
+ * When a libp2p node is provided, the underlying protocol is handled by
+ * strand-proto's SessionManager via StrandFormationManager.
+ */
+export class StrandSolicitationService {
+    constructor(options) {
+        this.disclosureValidator = options?.disclosureValidator;
+        this.formationUsageRecorder = options?.formationUsageRecorder;
+        this.strandProvisioner = options?.strandProvisioner;
+        this.formationSigner = options?.formationSigner;
+        this.partyId = options?.partyId ?? `party-${Date.now()}`;
+        this.cadrePeerAddrs = options?.cadrePeerAddrs ?? [];
+        this.formationConfig = options?.formationConfig;
+        log('StrandSolicitationService created for party: %s', this.partyId);
+    }
+    /**
+     * Get or create the StrandFormationManager.
+     * Lazily initialized to allow configuration after construction.
+     */
+    getFormationManager() {
+        if (!this.formationManager) {
+            this.formationManager = new StrandFormationManager({
+                disclosureValidator: this.disclosureValidator,
+                formationUsageRecorder: this.formationUsageRecorder,
+                strandProvisioner: this.strandProvisioner,
+                partyId: this.partyId,
+                cadrePeerAddrs: this.cadrePeerAddrs,
+                config: this.formationConfig
+            });
+        }
+        return this.formationManager;
+    }
+    /**
+     * Register as a responder on a libp2p node.
+     * This enables the node to handle incoming strand formation requests.
+     */
+    registerResponder(node) {
+        this.getFormationManager().registerResponder(node);
+        log('Registered as responder');
+    }
+    /**
+     * Unregister as a responder from a libp2p node.
+     */
+    unregisterResponder(node) {
+        this.getFormationManager().unregisterResponder(node);
+        log('Unregistered as responder');
+    }
+    /**
+     * Form a strand with a responder via an open invitation.
+     *
+     * Called by the initiator (the party who received an out-of-band invitation).
+     * This generates a member key, contacts the responder's cadre, and negotiates
+     * strand formation.
+     *
+     * @param invitation The open invitation (or just token for legacy API)
+     * @param disclosure Identity/context information to share with the responder
+     * @param node Optional libp2p node for real protocol handling
+     * @returns The member key and strand info if successful
+     */
+    async formStrand(invitation, disclosure, node) {
+        // Handle legacy API where just token was passed
+        const token = typeof invitation === 'string' ? invitation : invitation.token;
+        log('Forming strand with token: %s', token);
+        // Generate a new keypair for this strand membership
+        const privateKey = await generateKeyPair('Ed25519');
+        const peerId = peerIdFromPrivateKey(privateKey);
+        const privateKeyBytes = privateKeyToProtobuf(privateKey);
+        const memberKey = peerId.toString();
+        const invitePrivateKey = uint8ArrayToString(privateKeyBytes, 'base64');
+        log('Generated member key: %s', memberKey);
+        // If we have a full invitation and a node, use the real protocol
+        if (typeof invitation !== 'string' && node) {
+            log('Using strand-proto for real protocol handling');
+            const result = await this.getFormationManager().formStrand(invitation, { ...disclosure, partyId: memberKey }, node);
+            return {
+                memberKey,
+                invitePrivateKey,
+                strandId: result.strandId
+            };
+        }
+        // Fallback: placeholder strandId (for testing without network)
+        log('No node provided, using placeholder strandId');
+        const strandId = `strand-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        return {
+            memberKey,
+            invitePrivateKey,
+            strandId
+        };
+    }
+    /**
+     * Validate a strand formation request.
+     *
+     * Called by the responder (the party who created the open invitation) when
+     * an initiator contacts them to form a strand. Validates the disclosure
+     * and returns a signed approval.
+     *
+     * @param token The invitation token being used
+     * @param disclosure The disclosure from the initiator
+     * @returns Validation key and signature if approved
+     * @throws If validation fails or token is invalid
+     */
+    async validateStrandFormation(token, disclosure) {
+        log('Validating strand formation for token: %s', token);
+        // Check token validity
+        if (this.formationUsageRecorder) {
+            const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
+            if (!tokenCheck.valid) {
+                log('Token invalid or expired: %s', token);
+                throw new Error('Invalid or expired token');
+            }
+            // Check if already used (for single-use tokens)
+            const isUsed = await this.formationUsageRecorder.isTokenUsed(token);
+            if (isUsed) {
+                log('Token already used: %s', token);
+                throw new Error('Token has already been used');
+            }
+        }
+        // Validate the disclosure
+        if (this.disclosureValidator) {
+            const isValid = await this.disclosureValidator.validateDisclosure(token, disclosure);
+            if (!isValid) {
+                log('Disclosure validation failed for token: %s', token);
+                throw new Error('Disclosure validation failed');
+            }
+        }
+        // Sign the formation approval
+        if (!this.formationSigner) {
+            throw new Error('FormationSigner not configured');
+        }
+        const { validationKey, validationSignature } = await this.formationSigner.signFormation(token, disclosure);
+        log('Formation validated, key: %s', validationKey);
+        return {
+            validationKey,
+            validationSignature
+        };
+    }
+    /**
+     * Create an open invitation for others to form strands with this party.
+     *
+     * @param sAppId The sApp to use for formed strands
+     * @param expirationMs How long the invitation is valid (ms from now)
+     * @param bootstrap Bootstrap addresses for contacting this party's cadre
+     * @returns The open invitation to share out-of-band
+     */
+    async createOpenInvitation(sAppId, expirationMs, bootstrap) {
+        // Generate a unique token
+        const token = `invite-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+        const expiration = new Date(Date.now() + expirationMs);
+        log('Created open invitation: %s (expires %s)', token, expiration.toISOString());
+        return {
+            token,
+            sAppId,
+            expiration,
+            bootstrap
+        };
+    }
+    /**
+     * Record that a formation was completed successfully.
+     * Called after strand provisioning to track usage.
+     */
+    async recordFormationComplete(token, initiatorKey, strandId) {
+        if (this.formationUsageRecorder) {
+            await this.formationUsageRecorder.recordUsage(token, initiatorKey, strandId);
+            log('Recorded formation usage: token=%s strand=%s', token, strandId);
+        }
+    }
+}
+//# sourceMappingURL=strand-solicitation.js.map

package/dist/strand-solicitation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-solicitation.js","sourceRoot":"","sources":["../src/strand-solicitation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAQvD,OAAO,EACL,sBAAsB,EAEvB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,GAAG,GAAG,KAAK,CAAC,2BAA2B,CAAC,CAAC;AA2E/C;;;;;;;;;GASG;AACH,MAAM,OAAO,yBAAyB;IAUpC,YAAY,OAA0C;QACpD,IAAI,CAAC,mBAAmB,GAAG,OAAO,EAAE,mBAAmB,CAAC;QACxD,IAAI,CAAC,sBAAsB,GAAG,OAAO,EAAE,sBAAsB,CAAC;QAC9D,IAAI,CAAC,iBAAiB,GAAG,OAAO,EAAE,iBAAiB,CAAC;QACpD,IAAI,CAAC,eAAe,GAAG,OAAO,EAAE,eAAe,CAAC;QAChD,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,SAAS,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACzD,IAAI,CAAC,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,EAAE,CAAC;QACpD,IAAI,CAAC,eAAe,GAAG,OAAO,EAAE,eAAe,CAAC;QAChD,GAAG,CAAC,iDAAiD,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACvE,CAAC;IAED;;;OAGG;IACK,mBAAmB;QACzB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,IAAI,CAAC,gBAAgB,GAAG,IAAI,sBAAsB,CAAC;gBACjD,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;gBAC7C,sBAAsB,EAAE,IAAI,CAAC,sBAAsB;gBACnD,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;gBACzC,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,MAAM,EAAE,IAAI,CAAC,eAAe;aAC7B,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,IAAY;QAC5B,IAAI,CAAC,mBAAmB,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACnD,GAAG,CAAC,yBAAyB,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,mBAAmB,CAAC,IAAY;QAC9B,IAAI,CAAC,mBAAmB,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACrD,GAAG,CAAC,2BAA2B,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,UAAU,CACd,UAAmC,EACnC,UAAqC,EACrC,IAAa;QAEb,gDAAgD;QAChD,MAAM,KAAK,GAAG,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC;QAC7E,GAAG,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;QAE5C,oDAAoD;QACpD,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAChD,MAAM,eAAe,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAEzD,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;QAEvE,GAAG,CAAC,0BAA0B,EAAE,SAAS,CAAC,CAAC;QAE3C,iEAAiE;QACjE,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,IAAI,EAAE,CAAC;YAC3C,GAAG,CAAC,+CAA+C,CAAC,CAAC;YACrD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC,UAAU,CACxD,UAAU,EACV,EAAE,GAAG,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,EACrC,IAAI,CACL,CAAC;YACF,OAAO;gBACL,SAAS;gBACT,gBAAgB;gBAChB,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B,CAAC;QACJ,CAAC;QAED,+DAA+D;QAC/D,GAAG,CAAC,8CAA8C,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,UAAU,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAElF,OAAO;YACL,SAAS;YACT,gBAAgB;YAChB,QAAQ;SACT,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,uBAAuB,CAC3B,KAAa,EACb,UAAqC;QAErC,GAAG,CAAC,2CAA2C,EAAE,KAAK,CAAC,CAAC;QAExD,uBAAuB;QACvB,IAAI,IAAI,CAAC,sBAAsB,EAAE,CAAC;YAChC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YACzE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBACtB,GAAG,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;gBAC3C,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;YAC9C,CAAC;YAED,gDAAgD;YAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YACpE,IAAI,MAAM,EAAE,CAAC;gBACX,GAAG,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;QAED,0BAA0B;QAC1B,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YACrF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,GAAG,CAAC,4CAA4C,EAAE,KAAK,CAAC,CAAC;gBACzD,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;QAED,8BAA8B;QAC9B,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,EAAE,aAAa,EAAE,mBAAmB,EAAE,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,aAAa,CACrF,KAAK,EACL,UAAU,CACX,CAAC;QAEF,GAAG,CAAC,8BAA8B,EAAE,aAAa,CAAC,CAAC;QAEnD,OAAO;YACL,aAAa;YACb,mBAAmB;SACpB,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,oBAAoB,CACxB,MAAc,EACd,YAAoB,EACpB,SAAmB;QAEnB,0BAA0B;QAC1B,MAAM,KAAK,GAAG,UAAU,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;QAChF,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC;QAEvD,GAAG,CAAC,0CAA0C,EAAE,KAAK,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;QAEjF,OAAO;YACL,KAAK;YACL,MAAM;YACN,UAAU;YACV,SAAS;SACV,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,uBAAuB,CAC3B,KAAa,EACb,YAAoB,EACpB,QAAgB;QAEhB,IAAI,IAAI,CAAC,sBAAsB,EAAE,CAAC;YAChC,MAAM,IAAI,CAAC,sBAAsB,CAAC,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;YAC7E,GAAG,CAAC,8CAA8C,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;CACF"}

package/dist/strand-watcher.d.ts

@@ -0,0 +1,70 @@
+import type { StrandFilter, StrandRow } from './types.js';
+/**
+ * Extended strand row that includes the sAppId for filtering purposes.
+ * The sAppId is provided by the hosting application, not from the control network.
+ */
+export interface StrandRowWithApp extends StrandRow {
+    /** sApp ID if known (for filtering) */
+    sAppId?: string;
+}
+/**
+ * Callback for strand changes
+ */
+export interface StrandWatcherCallbacks {
+    onStrandAdded: (strand: StrandRow) => Promise<void>;
+    onStrandRemoved: (strandId: string) => Promise<void>;
+}
+/**
+ * Interface for querying strands from control network
+ */
+export interface StrandQueryable {
+    queryStrands(): Promise<StrandRow[]>;
+}
+/**
+ * Interface for looking up sAppId for a strand (for filtering)
+ */
+export interface SAppIdLookup {
+    /** Get the sAppId for a strand, if known */
+    getSAppId(strandId: string): string | undefined;
+}
+/**
+ * Watches the control network's Strand table for changes and triggers
+ * strand instance start/stop via callbacks.
+ *
+ * Uses polling until Optimystic supports reactive subscriptions.
+ */
+export declare class StrandWatcher {
+    private readonly filter;
+    private readonly pollInterval;
+    private readonly callbacks;
+    private readonly queryable;
+    private readonly sAppIdLookup?;
+    private knownStrands;
+    private pollTimer;
+    private running;
+    constructor(queryable: StrandQueryable, callbacks: StrandWatcherCallbacks, filter?: StrandFilter, pollInterval?: number, sAppIdLookup?: SAppIdLookup);
+    /**
+     * Check if a strand passes the current filter
+     */
+    private passesFilter;
+    /**
+     * Poll for strand changes
+     */
+    private poll;
+    /**
+     * Start watching for strand changes
+     */
+    start(): Promise<void>;
+    /**
+     * Stop watching for strand changes
+     */
+    stop(): Promise<void>;
+    /**
+     * Get currently known strands
+     */
+    getKnownStrands(): Map<string, StrandRow>;
+    /**
+     * Force an immediate poll (useful for testing)
+     */
+    forcePoll(): Promise<void>;
+}

package/dist/strand-watcher.js

@@ -0,0 +1,136 @@
+import debug from 'debug';
+const log = debug('sereus:cadre:strand-watcher');
+/**
+ * Watches the control network's Strand table for changes and triggers
+ * strand instance start/stop via callbacks.
+ *
+ * Uses polling until Optimystic supports reactive subscriptions.
+ */
+export class StrandWatcher {
+    constructor(queryable, callbacks, filter = { mode: 'all' }, pollInterval = 5000, sAppIdLookup) {
+        this.knownStrands = new Map();
+        this.pollTimer = null;
+        this.running = false;
+        this.queryable = queryable;
+        this.callbacks = callbacks;
+        this.filter = filter;
+        this.pollInterval = pollInterval;
+        this.sAppIdLookup = sAppIdLookup;
+        log('StrandWatcher created with filter: %o, interval: %dms', filter, pollInterval);
+    }
+    /**
+     * Check if a strand passes the current filter
+     */
+    passesFilter(strand) {
+        switch (this.filter.mode) {
+            case 'all':
+                return true;
+            case 'none':
+                return false;
+            case 'strandId':
+                return strand.Id === this.filter.strandId;
+            case 'sAppId': {
+                // Look up the sAppId for this strand
+                const sAppId = this.sAppIdLookup?.getSAppId(strand.Id);
+                if (sAppId === undefined) {
+                    // If no sAppId lookup configured or unknown strand, pass through
+                    // The strand will need to be re-evaluated when sApp info is available
+                    log('sAppId unknown for strand %s - deferring filter decision', strand.Id);
+                    return true;
+                }
+                const matches = sAppId === this.filter.sAppId;
+                log('sAppId filter: strand %s has sAppId %s, filter wants %s, match=%s', strand.Id, sAppId, this.filter.sAppId, matches);
+                return matches;
+            }
+            default:
+                return true;
+        }
+    }
+    /**
+     * Poll for strand changes
+     */
+    async poll() {
+        if (!this.running)
+            return;
+        try {
+            const currentStrands = await this.queryable.queryStrands();
+            const currentMap = new Map(currentStrands.map(s => [s.Id, s]));
+            // Find added strands
+            for (const strand of currentStrands) {
+                if (!this.knownStrands.has(strand.Id) && this.passesFilter(strand)) {
+                    log('Strand added: %s', strand.Id);
+                    this.knownStrands.set(strand.Id, strand);
+                    try {
+                        await this.callbacks.onStrandAdded(strand);
+                    }
+                    catch (error) {
+                        log('Error handling strand add for %s: %o', strand.Id, error);
+                    }
+                }
+            }
+            // Find removed strands
+            for (const [strandId] of this.knownStrands) {
+                if (!currentMap.has(strandId)) {
+                    log('Strand removed: %s', strandId);
+                    this.knownStrands.delete(strandId);
+                    try {
+                        await this.callbacks.onStrandRemoved(strandId);
+                    }
+                    catch (error) {
+                        log('Error handling strand remove for %s: %o', strandId, error);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            log('Error polling strands: %o', error);
+        }
+    }
+    /**
+     * Start watching for strand changes
+     */
+    async start() {
+        if (this.running) {
+            log('StrandWatcher already running');
+            return;
+        }
+        log('Starting StrandWatcher');
+        this.running = true;
+        // Do an initial poll immediately
+        await this.poll();
+        // Set up periodic polling
+        this.pollTimer = setInterval(() => {
+            void this.poll();
+        }, this.pollInterval);
+        log('StrandWatcher started');
+    }
+    /**
+     * Stop watching for strand changes
+     */
+    async stop() {
+        if (!this.running) {
+            return;
+        }
+        log('Stopping StrandWatcher');
+        this.running = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.knownStrands.clear();
+        log('StrandWatcher stopped');
+    }
+    /**
+     * Get currently known strands
+     */
+    getKnownStrands() {
+        return new Map(this.knownStrands);
+    }
+    /**
+     * Force an immediate poll (useful for testing)
+     */
+    async forcePoll() {
+        await this.poll();
+    }
+}
+//# sourceMappingURL=strand-watcher.js.map

package/dist/strand-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-watcher.js","sourceRoot":"","sources":["../src/strand-watcher.ts"],"names":[],"mappings":"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"}