@claude-flow/plugin-agent-federation 1.0.0-alpha.8 → 1.0.0

package/dist/application/inbound-dispatcher.js

@@ -0,0 +1,356 @@
+/**
+ * Inbound message dispatcher (ADR-109).
+ *
+ * The federation plugin's `transport.listen()` accepts inbound bytes
+ * but until this module landed, the bytes had no consumer — they sat
+ * in the transport's per-address message queue with no one polling.
+ *
+ * `dispatchInbound()` is what the plugin registers as the
+ * transport.onMessage handler. For each received message it:
+ *
+ *   1. Resolves the sender via `sourceNodeId` in metadata
+ *   2. Verifies the peer is in the discovery registry (unknown → reject)
+ *   3. Verifies peer is ACTIVE (SUSPENDED/EVICTED → reject defense-in-depth)
+ *   4. Audits success or rejection
+ *   5. Emits a typed event on the eventBus for the integrator to handle
+ *
+ * Anti-coupling: dispatcher does NOT actually execute inbound tasks.
+ * That's the integrator's job. The dispatcher's contract is "deliver
+ * an envelope to the integrator's handler IFF it passes safety gates."
+ */
+import { FederationNodeState } from '../domain/value-objects/federation-node-state.js';
+/** What gets emitted on the event bus per messageType. */
+export const FEDERATION_INBOUND_EVENT_PREFIX = 'federation:inbound';
+export const JCS_SIGNATURE_PROTOCOL = 'ruflo-signature-jcs-v1';
+/**
+ * Updated peers advertise and negotiate recursively complete JCS signatures
+ * without operator configuration. Legacy mode remains explicit for low-risk
+ * heartbeat/status interoperability only.
+ */
+export const DEFAULT_ENVELOPE_SIGNATURE_MODE = 'prefer-jcs';
+/**
+ * The historical serializer does not authenticate nested payload fields.
+ * Keep it available only for messages whose payload cannot mutate federation
+ * state or transfer data/ownership. Unknown types are intentionally denied.
+ */
+const LEGACY_V1_LOW_RISK_MESSAGE_TYPES = new Set([
+    'heartbeat',
+    'status-broadcast',
+]);
+export function isLegacyEnvelopeTypeAllowed(messageType) {
+    return LEGACY_V1_LOW_RISK_MESSAGE_TYPES.has(messageType);
+}
+/**
+ * Canonical serialization of an envelope for signing. This is the
+ * RFC 8785/JCS-compatible subset used by federation v1 while v2 schema
+ * negotiation is introduced. It recursively sorts object keys and rejects
+ * values outside the I-JSON-safe subset instead of silently dropping them.
+ * The `signature` field itself is excluded because it is what we verify.
+ *
+ * Federation messages are wrapped as `AgentMessage{id, type, payload,
+ * metadata}` on the wire. The `payload` is the actual FederationEnvelope
+ * (per `plugin.ts sendToNode`); we canonicalize the payload + the
+ * metadata so the receiver verifies the same bytes the sender signed.
+ */
+function canonicalizeJcsValue(value, ancestors) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'string':
+            return JSON.stringify(value);
+        case 'number':
+            if (!Number.isFinite(value) || Object.is(value, -0)) {
+                throw new TypeError('Federation canonicalization rejects non-canonical numbers');
+            }
+            if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+                throw new TypeError('Federation canonicalization rejects unsafe integers');
+            }
+            return JSON.stringify(value);
+        case 'bigint':
+        case 'function':
+        case 'symbol':
+        case 'undefined':
+            throw new TypeError(`Federation canonicalization rejects ${typeof value}`);
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`Federation canonicalization rejects ${typeof value}`);
+    }
+    const object = value;
+    if (ancestors.has(object)) {
+        throw new TypeError('Federation canonicalization rejects cyclic values');
+    }
+    ancestors.add(object);
+    try {
+        if (Array.isArray(value)) {
+            const items = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                    throw new TypeError('Federation canonicalization rejects sparse arrays');
+                }
+                items.push(canonicalizeJcsValue(value[index], ancestors));
+            }
+            return `[${items.join(',')}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError('Federation canonicalization accepts only plain objects');
+        }
+        const record = value;
+        const entries = Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalizeJcsValue(record[key], ancestors)}`);
+        return `{${entries.join(',')}}`;
+    }
+    finally {
+        ancestors.delete(object);
+    }
+}
+function envelopeSignatureVersion(message) {
+    const version = message.metadata?.signatureVersion;
+    if (version === undefined)
+        return 'legacy-v1';
+    if (version === 'jcs-v1')
+        return version;
+    throw new TypeError(`Unsupported federation signature version: ${String(version)}`);
+}
+export function selectEnvelopeSignatureVersion(mode, peerProtocols, messageType) {
+    const selected = mode === 'legacy'
+        ? 'legacy-v1'
+        : peerProtocols.includes(JCS_SIGNATURE_PROTOCOL)
+            ? 'jcs-v1'
+            : mode === 'prefer-jcs'
+                ? 'legacy-v1'
+                : null;
+    if (selected === null) {
+        throw new Error('PEER_SIGNATURE_PROTOCOL_UNSUPPORTED');
+    }
+    if (selected === 'legacy-v1'
+        && messageType !== undefined
+        && !isLegacyEnvelopeTypeAllowed(messageType)) {
+        throw new Error(`PEER_SIGNATURE_PROTOCOL_UNSUPPORTED_FOR_MESSAGE: ${messageType}`);
+    }
+    return selected;
+}
+export function canonicalizeEnvelopeForVerify(message, requestedVersion) {
+    const meta = (message.metadata ?? {});
+    // Strip signature from metadata if present (we verify the rest)
+    const { signature: _sig, ...metaForSig } = meta;
+    const canon = {
+        id: message.id,
+        type: message.type,
+        payload: message.payload,
+        metadata: metaForSig,
+    };
+    const version = requestedVersion ?? envelopeSignatureVersion(message);
+    if (version === 'legacy-v1') {
+        // Byte-for-byte compatibility with releases through 1.0.0-alpha.16.
+        // Its recursive array replacer omits nested fields, so legacy messages
+        // cannot become privileged ownership mutations.
+        return JSON.stringify(canon, Object.keys(canon).sort());
+    }
+    return canonicalizeJcsValue(canon, new Set());
+}
+/**
+ * Process one received message. Pure-ish: no side effects beyond audit
+ * + event emission, both injected.
+ *
+ * `address` is the wire-level remote (e.g. `192.168.1.42:54321`).
+ * `message.metadata.sourceNodeId` is the cryptographic identity claim.
+ * The two MAY differ (e.g. behind NAT) — we trust `sourceNodeId` for
+ * peer lookup since it's bound to the Ed25519 keypair.
+ */
+export async function dispatchInbound(address, message, deps) {
+    const meta = (message.metadata ?? {});
+    const sourceNodeId = typeof meta.sourceNodeId === 'string' ? meta.sourceNodeId : null;
+    if (!sourceNodeId) {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId: undefined,
+            metadata: { address, reason: 'MISSING_METADATA' },
+        });
+        deps.logger.warn(`Inbound rejected: no sourceNodeId in metadata (from ${address})`);
+        return { accepted: false, reason: 'MISSING_METADATA' };
+    }
+    const peer = deps.discovery.getPeer(sourceNodeId);
+    if (!peer) {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId,
+            metadata: { address, reason: 'PEER_UNKNOWN' },
+        });
+        deps.logger.warn(`Inbound rejected: ${sourceNodeId} not in discovery (from ${address})`);
+        return { accepted: false, reason: 'PEER_UNKNOWN' };
+    }
+    if (peer.state === FederationNodeState.SUSPENDED) {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId,
+            metadata: { address, reason: 'PEER_SUSPENDED' },
+        });
+        return { accepted: false, reason: 'PEER_SUSPENDED' };
+    }
+    if (peer.state === FederationNodeState.EVICTED) {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId,
+            metadata: { address, reason: 'PEER_EVICTED' },
+        });
+        return { accepted: false, reason: 'PEER_EVICTED' };
+    }
+    let signatureVersion;
+    let canonicalEnvelope;
+    try {
+        signatureVersion = envelopeSignatureVersion(message);
+        const accepted = deps.acceptedSignatureVersions ?? ['legacy-v1', 'jcs-v1'];
+        if (!accepted.includes(signatureVersion)) {
+            throw new TypeError(`Signature version ${signatureVersion} is disabled`);
+        }
+        canonicalEnvelope = canonicalizeEnvelopeForVerify(message, signatureVersion);
+    }
+    catch {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId,
+            metadata: { address, reason: 'INVALID_PAYLOAD' },
+        });
+        deps.logger.warn(`Inbound rejected: non-canonical payload from ${sourceNodeId} (addr=${address})`);
+        return { accepted: false, reason: 'INVALID_PAYLOAD' };
+    }
+    // Cryptographic signature verification (closes the trust gate that
+    // peer-state checks alone don't provide — without this, a malicious
+    // sender could just claim sourceNodeId='known-peer' in metadata and
+    // pass the previous gates).
+    if (deps.verifyEnvelope) {
+        const sig = typeof meta.signature === 'string' ? meta.signature : null;
+        let ok = false;
+        try {
+            ok = deps.verifyEnvelope(canonicalEnvelope, sig, peer.publicKey);
+        }
+        catch {
+            await deps.audit.log('message_rejected', {
+                sourceNodeId,
+                metadata: { address, reason: 'INVALID_PAYLOAD' },
+            });
+            deps.logger.warn(`Inbound rejected: non-canonical payload from ${sourceNodeId} (addr=${address})`);
+            return { accepted: false, reason: 'INVALID_PAYLOAD' };
+        }
+        if (!ok) {
+            await deps.audit.log('message_rejected', {
+                sourceNodeId,
+                metadata: { address, reason: 'INVALID_SIGNATURE' },
+            });
+            deps.logger.warn(`Inbound rejected: bad signature from ${sourceNodeId} (addr=${address})`);
+            return { accepted: false, reason: 'INVALID_SIGNATURE' };
+        }
+    }
+    // The legacy serializer omits nested fields. No policy grant can make those
+    // unauthenticated bytes safe for a consequential operation, so this gate is
+    // independent of authorization compatibility mode.
+    if (signatureVersion === 'legacy-v1' &&
+        !isLegacyEnvelopeTypeAllowed(message.type)) {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId,
+            metadata: {
+                address,
+                reason: 'LEGACY_SIGNATURE_TYPE_REJECTED',
+                messageType: message.type,
+            },
+        });
+        deps.logger.warn(`Inbound rejected: legacy-v1 is not permitted for message type ${message.type} ` +
+            `from ${sourceNodeId}`);
+        return { accepted: false, reason: 'LEGACY_SIGNATURE_TYPE_REJECTED' };
+    }
+    const authorizationMode = deps.authorizationMode ?? 'legacy';
+    if (authorizationMode !== 'legacy' &&
+        authorizationMode !== 'observe' &&
+        authorizationMode !== 'enforce') {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId,
+            metadata: { address, reason: 'AUTHORIZATION_ERROR' },
+        });
+        return { accepted: false, reason: 'AUTHORIZATION_ERROR' };
+    }
+    let authorizationDecision;
+    if (deps.authorizeInbound) {
+        try {
+            const decision = await deps.authorizeInbound({
+                address,
+                sourceNodeId,
+                messageType: message.type,
+                message,
+                peer,
+                signatureVersion,
+                messageSizeBytes: new TextEncoder().encode(canonicalEnvelope).byteLength,
+            });
+            if (!decision || typeof decision.allowed !== 'boolean') {
+                throw new TypeError('Inbound authorization evaluator returned an invalid decision');
+            }
+            authorizationDecision = decision;
+        }
+        catch {
+            if (authorizationMode === 'enforce') {
+                await deps.audit.log('message_rejected', {
+                    sourceNodeId,
+                    metadata: { address, reason: 'AUTHORIZATION_ERROR', messageType: message.type },
+                });
+                deps.logger.warn(`Inbound authorization failed for ${sourceNodeId} (addr=${address})`);
+                return { accepted: false, reason: 'AUTHORIZATION_ERROR' };
+            }
+            deps.logger.warn(`Inbound authorization observation failed for ${sourceNodeId} (mode=${authorizationMode})`);
+        }
+    }
+    else if (authorizationMode === 'enforce') {
+        await deps.audit.log('message_rejected', {
+            sourceNodeId,
+            metadata: { address, reason: 'AUTHORIZATION_ERROR', messageType: message.type },
+        });
+        deps.logger.warn('Inbound rejected: enforce mode has no authorization evaluator');
+        return { accepted: false, reason: 'AUTHORIZATION_ERROR' };
+    }
+    if (authorizationDecision && !authorizationDecision.allowed) {
+        if (authorizationMode === 'enforce') {
+            await deps.audit.log('message_rejected', {
+                sourceNodeId,
+                metadata: {
+                    address,
+                    reason: 'AUTHORIZATION_DENIED',
+                    messageType: message.type,
+                    policyReason: authorizationDecision.reason,
+                },
+            });
+            deps.logger.warn(`Inbound authorization denied for ${sourceNodeId} (addr=${address})`);
+            return { accepted: false, reason: 'AUTHORIZATION_DENIED' };
+        }
+        deps.logger.warn(`Inbound authorization would deny ${message.type} from ${sourceNodeId} ` +
+            `(mode=${authorizationMode})`);
+    }
+    // Touch lastSeen on every successful inbound — drives the
+    // discovery service's stale-peer detection.
+    peer.markSeen();
+    // Audit accepted delivery
+    await deps.audit.log('message_received', {
+        sourceNodeId,
+        metadata: {
+            address,
+            messageType: message.type,
+            messageId: message.id,
+            authorizationMode,
+            authorizationAllowed: authorizationDecision?.allowed,
+        },
+    });
+    // Emit typed event for the integrator
+    // Examples: federation:inbound:task, federation:inbound:memory-query
+    const eventName = `${FEDERATION_INBOUND_EVENT_PREFIX}:${message.type}`;
+    try {
+        deps.eventBus.emit(eventName, {
+            address,
+            sourceNodeId,
+            message,
+            peer,
+        });
+    }
+    catch (err) {
+        // EventBus throw should not crash the receive loop.
+        deps.logger.warn(`EventBus emit failed for ${eventName}: ${err instanceof Error ? err.message : err}`);
+    }
+    return { accepted: true, sourceNodeId, messageType: message.type };
+}
+//# sourceMappingURL=inbound-dispatcher.js.map

package/dist/application/inbound-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-dispatcher.js","sourceRoot":"","sources":["../../src/application/inbound-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAEvF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,+BAA+B,GAAG,oBAAoB,CAAC;AA8BpE,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAiC,CAAC;AAGxE;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA0B,YAAY,CAAC;AAGnF;;;;GAIG;AACH,MAAM,gCAAgC,GAAwB,IAAI,GAAG,CAAC;IACpE,WAAW;IACX,kBAAkB;CACnB,CAAC,CAAC;AAEH,MAAM,UAAU,2BAA2B,CAAC,WAAmB;IAC7D,OAAO,gCAAgC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AAC3D,CAAC;AAgDD;;;;;;;;;;;GAWG;AACH,SAAS,oBAAoB,CAAC,KAAc,EAAE,SAAsB;IAClE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAElC,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,QAAQ;YACX,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpD,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;YACnF,CAAC;YACD,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5D,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;YAC7E,CAAC;YACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,QAAQ,CAAC;QACd,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ,CAAC;QACd,KAAK,WAAW;YACd,MAAM,IAAI,SAAS,CAAC,uCAAuC,OAAO,KAAK,EAAE,CAAC,CAAC;QAC7E,KAAK,QAAQ;YACX,MAAM;QACR;YACE,MAAM,IAAI,SAAS,CAAC,uCAAuC,OAAO,KAAK,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,MAAM,MAAM,GAAG,KAAe,CAAC;IAC/B,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;IAC3E,CAAC;IACD,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAEtB,IAAI,CAAC;QACH,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBACrD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;oBACxD,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;gBAC3E,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;YAC5D,CAAC;YACD,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAChC,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACzD,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;QAChF,CAAC;QAED,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;aAChC,IAAI,EAAE;aACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClC,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB,CAAC,OAAqB;IACrD,MAAM,OAAO,GAAI,OAAO,CAAC,QAAgD,EAAE,gBAAgB,CAAC;IAC5F,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC9C,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IACzC,MAAM,IAAI,SAAS,CAAC,6CAA6C,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,8BAA8B,CAC5C,IAA2B,EAC3B,aAAgC,EAChC,WAAoB;IAEpB,MAAM,QAAQ,GAAG,IAAI,KAAK,QAAQ;QAChC,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,sBAAsB,CAAC;YAC9C,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,IAAI,KAAK,YAAY;gBACrB,CAAC,CAAC,WAAW;gBACb,CAAC,CAAC,IAAI,CAAC;IACb,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,IACE,QAAQ,KAAK,WAAW;WACrB,WAAW,KAAK,SAAS;WACzB,CAAC,2BAA2B,CAAC,WAAW,CAAC,EAC5C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,oDAAoD,WAAW,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,OAAqB,EACrB,gBAA2C;IAE3C,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAA4B,CAAC;IACjE,gEAAgE;IAChE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC;IAChD,MAAM,KAAK,GAAG;QACZ,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,UAAU;KACrB,CAAC;IACF,MAAM,OAAO,GAAG,gBAAgB,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACtE,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;QAC5B,oEAAoE;QACpE,uEAAuE;QACvE,gDAAgD;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;AAChD,CAAC;AAOD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,OAAqB,EACrB,IAAyB;IAEzB,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAA4B,CAAC;IACjE,MAAM,YAAY,GAAG,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtF,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY,EAAE,SAAS;YACvB,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE;SAClD,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,uDAAuD,OAAO,GAAG,CAAC,CAAC;QACpF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY;YACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,qBAAqB,YAAY,2BAA2B,OAAO,GAAG,CAAC,CAAC;QACzF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACrD,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,KAAK,mBAAmB,CAAC,SAAS,EAAE,CAAC;QACjD,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY;YACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE;SAChD,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACvD,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,KAAK,mBAAmB,CAAC,OAAO,EAAE,CAAC;QAC/C,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY;YACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE;SAC9C,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACrD,CAAC;IAED,IAAI,gBAA0C,CAAC;IAC/C,IAAI,iBAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,gBAAgB,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,yBAAyB,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC3E,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,SAAS,CAAC,qBAAqB,gBAAgB,cAAc,CAAC,CAAC;QAC3E,CAAC;QACD,iBAAiB,GAAG,6BAA6B,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY;YACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE;SACjD,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gDAAgD,YAAY,UAAU,OAAO,GAAG,CAAC,CAAC;QACnG,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACxD,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,oEAAoE;IACpE,4BAA4B;IAC5B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;QACvE,IAAI,EAAE,GAAG,KAAK,CAAC;QACf,IAAI,CAAC;YACH,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC,iBAAiB,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;gBACvC,YAAY;gBACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE;aACjD,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gDAAgD,YAAY,UAAU,OAAO,GAAG,CAAC,CAAC;YACnG,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;gBACvC,YAAY;gBACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE;aACnD,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wCAAwC,YAAY,UAAU,OAAO,GAAG,CAAC,CAAC;YAC3F,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,mDAAmD;IACnD,IACE,gBAAgB,KAAK,WAAW;QAChC,CAAC,2BAA2B,CAAC,OAAO,CAAC,IAAI,CAAC,EAC1C,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY;YACZ,QAAQ,EAAE;gBACR,OAAO;gBACP,MAAM,EAAE,gCAAgC;gBACxC,WAAW,EAAE,OAAO,CAAC,IAAI;aAC1B;SACF,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,iEAAiE,OAAO,CAAC,IAAI,GAAG;YAC9E,QAAQ,YAAY,EAAE,CACzB,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;IACvE,CAAC;IAED,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,QAAQ,CAAC;IAC7D,IACE,iBAAiB,KAAK,QAAQ;QAC9B,iBAAiB,KAAK,SAAS;QAC/B,iBAAiB,KAAK,SAAS,EAC/B,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY;YACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE;SACrD,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAC5D,CAAC;IAED,IAAI,qBAA+D,CAAC;IACpE,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC;gBAC3C,OAAO;gBACP,YAAY;gBACZ,WAAW,EAAE,OAAO,CAAC,IAAI;gBACzB,OAAO;gBACP,IAAI;gBACJ,gBAAgB;gBAChB,gBAAgB,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,UAAU;aACzE,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBACvD,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;YACtF,CAAC;YACD,qBAAqB,GAAG,QAAQ,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;gBACpC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;oBACvC,YAAY;oBACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE;iBAChF,CAAC,CAAC;gBACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oCAAoC,YAAY,UAAU,OAAO,GAAG,CAAC,CAAC;gBACvF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;YAC5D,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,gDAAgD,YAAY,UAAU,iBAAiB,GAAG,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;YACvC,YAAY;YACZ,QAAQ,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE;SAChF,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;QAClF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAC5D,CAAC;IAED,IAAI,qBAAqB,IAAI,CAAC,qBAAqB,CAAC,OAAO,EAAE,CAAC;QAC5D,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;gBACvC,YAAY;gBACZ,QAAQ,EAAE;oBACR,OAAO;oBACP,MAAM,EAAE,sBAAsB;oBAC9B,WAAW,EAAE,OAAO,CAAC,IAAI;oBACzB,YAAY,EAAE,qBAAqB,CAAC,MAAM;iBAC3C;aACF,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oCAAoC,YAAY,UAAU,OAAO,GAAG,CAAC,CAAC;YACvF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,oCAAoC,OAAO,CAAC,IAAI,SAAS,YAAY,GAAG;YACtE,SAAS,iBAAiB,GAAG,CAChC,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,4CAA4C;IAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;IAEhB,0BAA0B;IAC1B,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,EAAE;QACvC,YAAY;QACZ,QAAQ,EAAE;YACR,OAAO;YACP,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,iBAAiB;YACjB,oBAAoB,EAAE,qBAAqB,EAAE,OAAO;SACrD;KACF,CAAC,CAAC;IAEH,sCAAsC;IACtC,qEAAqE;IACrE,MAAM,SAAS,GAAG,GAAG,+BAA+B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IACvE,IAAI,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE;YAC5B,OAAO;YACP,YAAY;YACZ,OAAO;YACP,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,oDAAoD;QACpD,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,4BAA4B,SAAS,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CACrF,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;AACrE,CAAC"}

package/dist/application/spend-reporter.d.ts

@@ -70,4 +70,81 @@ export declare class InMemorySpendReporter implements SpendReporter {
     /** Drop everything (test cleanup). */
     clear(): void;
 }
+/**
+ * Minimal memory-backend interface (ADR-110). The integrator wires this
+ * to whatever store satisfies their durability/consistency needs:
+ * ruflo memory, Redis, DynamoDB, file-backed JSON, etc. The federation
+ * plugin doesn't import any specific memory client — pluggable by
+ * design.
+ */
+export interface MemoryStore {
+    /** Persist a value under (namespace, key). Optional TTL in seconds. */
+    store(args: {
+        namespace: string;
+        key: string;
+        value: string;
+        ttl?: number;
+    }): Promise<void>;
+}
+/** Configuration for `MemorySpendReporter`. See ADR-110. */
+export interface MemorySpendReporterConfig {
+    /** Memory store impl. Required. */
+    readonly memoryStore: MemoryStore;
+    /** Namespace per the cost-tracker consumer contract. Default: `federation-spend`. */
+    readonly namespace?: string;
+    /** Optional TTL in seconds. Default: 7 days. Cost-tracker rolling windows are 1h/24h/7d, so anything older is irrelevant. */
+    readonly ttlSeconds?: number;
+}
+/** Default namespace per cost-tracker's `plugins/ruflo-cost-tracker/scripts/federation.mjs`. */
+export declare const DEFAULT_FEDERATION_SPEND_NAMESPACE = "federation-spend";
+/** Default TTL: 7 days, matching cost-tracker's longest rolling window. */
+export declare const DEFAULT_FEDERATION_SPEND_TTL_SECONDS: number;
+/**
+ * Production reporter (ADR-110) that satisfies the cost-tracker
+ * consumer contract: writes to namespace `federation-spend`, key
+ * `fed-spend-<peerId>-<ts>`. The consumer
+ * (`plugins/ruflo-cost-tracker/scripts/federation.mjs`) `memory list`s
+ * the namespace, retrieves each key, and aggregates into rolling
+ * windows.
+ *
+ * Storage-agnostic: the integrator injects a `MemoryStore`
+ * implementation. Common wirings:
+ *
+ *   // ruflo memory MCP
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async (a) => mcpClient.call('memory_store', a),
+ *     },
+ *   });
+ *
+ *   // ruflo memory CLI shell-out
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async ({namespace, key, value, ttl}) => {
+ *         await execFile('npx', ['ruflo', 'memory', 'store',
+ *           '--namespace', namespace, '--key', key, '--value', value]);
+ *       },
+ *     },
+ *   });
+ *
+ * Errors from the memory backend BUBBLE UP — the reporter does not
+ * retry/swallow. Wrap with the integrator's preferred retry strategy
+ * if needed.
+ *
+ * Negative `tokensUsed` / `usdSpent` are persisted as-is. Clamping is
+ * the breaker's responsibility (see federation-breaker-service.ts);
+ * the audit/spend log is an honest mirror of what the integrator
+ * reported.
+ */
+export declare class MemorySpendReporter implements SpendReporter {
+    private readonly memoryStore;
+    private readonly namespace;
+    private readonly ttlSeconds;
+    constructor(config: MemorySpendReporterConfig);
+    reportSpend(event: FederationSpendEvent): Promise<void>;
+    /** Read configured namespace (for the doctor/debug surface). */
+    getNamespace(): string;
+    /** Read configured TTL in seconds. */
+    getTtlSeconds(): number;
+}
 //# sourceMappingURL=spend-reporter.d.ts.map

package/dist/application/spend-reporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spend-reporter.d.ts","sourceRoot":"","sources":["../../src/application/spend-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IAE/C,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D,yDAAyD;IACzD,SAAS,IAAI,SAAS,oBAAoB,EAAE;IAI5C,sCAAsC;IACtC,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"spend-reporter.d.ts","sourceRoot":"","sources":["../../src/application/spend-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IAE/C,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D,yDAAyD;IACzD,SAAS,IAAI,SAAS,oBAAoB,EAAE;IAI5C,sCAAsC;IACtC,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,KAAK,CAAC,IAAI,EAAE;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6HAA6H;IAC7H,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,gGAAgG;AAChG,eAAO,MAAM,kCAAkC,qBAAqB,CAAC;AAErE,2EAA2E;AAC3E,eAAO,MAAM,oCAAoC,QAAmB,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,yBAAyB;IAMvC,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7D,gEAAgE;IAChE,YAAY,IAAI,MAAM;IAItB,sCAAsC;IACtC,aAAa,IAAI,MAAM;CAGxB"}

package/dist/application/spend-reporter.js

@@ -49,4 +49,80 @@ export class InMemorySpendReporter {
         this.buffer.length = 0;
     }
 }
+/** Default namespace per cost-tracker's `plugins/ruflo-cost-tracker/scripts/federation.mjs`. */
+export const DEFAULT_FEDERATION_SPEND_NAMESPACE = 'federation-spend';
+/** Default TTL: 7 days, matching cost-tracker's longest rolling window. */
+export const DEFAULT_FEDERATION_SPEND_TTL_SECONDS = 7 * 24 * 60 * 60;
+/**
+ * Production reporter (ADR-110) that satisfies the cost-tracker
+ * consumer contract: writes to namespace `federation-spend`, key
+ * `fed-spend-<peerId>-<ts>`. The consumer
+ * (`plugins/ruflo-cost-tracker/scripts/federation.mjs`) `memory list`s
+ * the namespace, retrieves each key, and aggregates into rolling
+ * windows.
+ *
+ * Storage-agnostic: the integrator injects a `MemoryStore`
+ * implementation. Common wirings:
+ *
+ *   // ruflo memory MCP
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async (a) => mcpClient.call('memory_store', a),
+ *     },
+ *   });
+ *
+ *   // ruflo memory CLI shell-out
+ *   new MemorySpendReporter({
+ *     memoryStore: {
+ *       store: async ({namespace, key, value, ttl}) => {
+ *         await execFile('npx', ['ruflo', 'memory', 'store',
+ *           '--namespace', namespace, '--key', key, '--value', value]);
+ *       },
+ *     },
+ *   });
+ *
+ * Errors from the memory backend BUBBLE UP — the reporter does not
+ * retry/swallow. Wrap with the integrator's preferred retry strategy
+ * if needed.
+ *
+ * Negative `tokensUsed` / `usdSpent` are persisted as-is. Clamping is
+ * the breaker's responsibility (see federation-breaker-service.ts);
+ * the audit/spend log is an honest mirror of what the integrator
+ * reported.
+ */
+export class MemorySpendReporter {
+    memoryStore;
+    namespace;
+    ttlSeconds;
+    constructor(config) {
+        this.memoryStore = config.memoryStore;
+        this.namespace = config.namespace ?? DEFAULT_FEDERATION_SPEND_NAMESPACE;
+        this.ttlSeconds = config.ttlSeconds ?? DEFAULT_FEDERATION_SPEND_TTL_SECONDS;
+    }
+    async reportSpend(event) {
+        const key = `fed-spend-${event.peerId}-${event.ts}`;
+        const value = JSON.stringify({
+            peerId: event.peerId,
+            taskId: event.taskId ?? null,
+            tokensUsed: event.tokensUsed,
+            usdSpent: event.usdSpent,
+            success: event.success,
+            ts: event.ts,
+        });
+        await this.memoryStore.store({
+            namespace: this.namespace,
+            key,
+            value,
+            ttl: this.ttlSeconds,
+        });
+    }
+    /** Read configured namespace (for the doctor/debug surface). */
+    getNamespace() {
+        return this.namespace;
+    }
+    /** Read configured TTL in seconds. */
+    getTtlSeconds() {
+        return this.ttlSeconds;
+    }
+}
 //# sourceMappingURL=spend-reporter.js.map

package/dist/application/spend-reporter.js.map

@@ -1 +1 @@
-{"version":3,"file":"spend-reporter.js","sourceRoot":"","sources":["../../src/application/spend-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+BH;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAqB;IACf,MAAM,GAA2B,EAAE,CAAC;IAErD,KAAK,CAAC,WAAW,CAAC,KAA2B;QAC3C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,yDAAyD;IACzD,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,sCAAsC;IACtC,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"spend-reporter.js","sourceRoot":"","sources":["../../src/application/spend-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+BH;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAqB;IACf,MAAM,GAA2B,EAAE,CAAC;IAErD,KAAK,CAAC,WAAW,CAAC,KAA2B;QAC3C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,yDAAyD;IACzD,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,sCAAsC;IACtC,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;CACF;AA6BD,gGAAgG;AAChG,MAAM,CAAC,MAAM,kCAAkC,GAAG,kBAAkB,CAAC;AAErE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,OAAO,mBAAmB;IACb,WAAW,CAAc;IACzB,SAAS,CAAS;IAClB,UAAU,CAAS;IAEpC,YAAY,MAAiC;QAC3C,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,kCAAkC,CAAC;QACxE,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,oCAAoC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAA2B;QAC3C,MAAM,GAAG,GAAG,aAAa,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;YAC3B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;YAC5B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,EAAE,EAAE,KAAK,CAAC,EAAE;SACb,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG;YACH,KAAK;YACL,GAAG,EAAE,IAAI,CAAC,UAAU;SACrB,CAAC,CAAC;IACL,CAAC;IAED,gEAAgE;IAChE,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,sCAAsC;IACtC,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;CACF"}

package/dist/application/trust-evaluator.d.ts

@@ -19,6 +19,21 @@ export type ImmediateDowngradeReason = 'repeated-threat-detection' | 'hmac-verif
 export interface TrustEvaluatorDeps {
     onTrustChange?: (nodeId: string, result: TrustTransitionResult) => void;
 }
+/**
+ * Audit record emitted by `bootstrapElevate`. Captures the bypass intent,
+ * the operator-supplied reason, and the before/after trust levels so that
+ * downstream audit consumers can flag bootstrap elevations distinctly from
+ * organic trust transitions. See ADR-164 §3.5.4.
+ */
+export interface BootstrapElevationAuditEntry {
+    readonly tag: 'bootstrap_elevation';
+    readonly nodeId: string;
+    readonly previousLevel: TrustLevel;
+    readonly newLevel: TrustLevel;
+    readonly reason: string;
+    readonly timestamp: string;
+    readonly operatorBypass: true;
+}
 export interface ThreatWindow {
     readonly detections: Date[];
     readonly windowMs: number;
@@ -34,6 +49,23 @@ export declare class TrustEvaluator {
     };
     evaluateTransition(node: FederationNode, metrics: SessionMetrics, uptimeRatio: number, hasInstitutionalAttestation?: boolean): TrustTransitionResult | null;
     downgrade(node: FederationNode, reason: ImmediateDowngradeReason): TrustTransitionResult;
+    /**
+     * Founder-bootstrap trust elevation (ADR-164 §3.5.4).
+     *
+     * Bypasses the organic trust-accrual thresholds (minInteractions: 500 for
+     * 2→3, etc.) so a freshly-joined BBS peer can be hand-promoted to
+     * TRUSTED on Day 1, before its interaction count has accrued. This is an
+     * operator escape hatch — every invocation MUST be recorded as a special
+     * `bootstrap_elevation` audit entry so it is distinguishable from organic
+     * upgrades. `reason` MUST be a non-empty operator-supplied string.
+     *
+     * The caller is responsible for refusing to invoke this method when the
+     * target node is not a registered federation peer; this function trusts
+     * its inputs and only performs the elevation + audit construction.
+     *
+     * @returns audit entry tagged `bootstrap_elevation` ready to be persisted.
+     */
+    bootstrapElevate(node: FederationNode, newLevel: TrustLevel, reason: string): BootstrapElevationAuditEntry;
     recordThreatDetection(nodeId: string): boolean;
     private checkUpgrade;
     private checkDowngrade;

package/dist/application/trust-evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust-evaluator.d.ts","sourceRoot":"","sources":["../../src/application/trust-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA+B,MAAM,mCAAmC,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,2BAA2B,GAC3B,wBAAwB,CAAC;AAE7B,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACzE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAQD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;gBAExC,IAAI,GAAE,kBAAuB;IAKzC,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,oBAAoB,CAAA;KAAE;IA8B/G,kBAAkB,CAChB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,MAAM,EACnB,2BAA2B,GAAE,OAAe,GAC3C,qBAAqB,GAAG,IAAI;IA4C/B,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,wBAAwB,GAAG,qBAAqB;IAmBxF,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAY9C,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,oBAAoB;CAK7B"}
+{"version":3,"file":"trust-evaluator.d.ts","sourceRoot":"","sources":["../../src/application/trust-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA+B,MAAM,mCAAmC,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,2BAA2B,GAC3B,wBAAwB,CAAC;AAE7B,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACzE;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAQD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;gBAExC,IAAI,GAAE,kBAAuB;IAKzC,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,oBAAoB,CAAA;KAAE;IA8B/G,kBAAkB,CAChB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,MAAM,EACnB,2BAA2B,GAAE,OAAe,GAC3C,qBAAqB,GAAG,IAAI;IA4C/B,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,wBAAwB,GAAG,qBAAqB;IAmBxF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CACd,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,MAAM,GACb,4BAA4B;IAoC/B,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAY9C,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,oBAAoB;CAK7B"}

package/dist/application/trust-evaluator.js

@@ -84,6 +84,53 @@ export class TrustEvaluator {
         this.deps.onTrustChange?.(node.nodeId, result);
         return result;
     }
+    /**
+     * Founder-bootstrap trust elevation (ADR-164 §3.5.4).
+     *
+     * Bypasses the organic trust-accrual thresholds (minInteractions: 500 for
+     * 2→3, etc.) so a freshly-joined BBS peer can be hand-promoted to
+     * TRUSTED on Day 1, before its interaction count has accrued. This is an
+     * operator escape hatch — every invocation MUST be recorded as a special
+     * `bootstrap_elevation` audit entry so it is distinguishable from organic
+     * upgrades. `reason` MUST be a non-empty operator-supplied string.
+     *
+     * The caller is responsible for refusing to invoke this method when the
+     * target node is not a registered federation peer; this function trusts
+     * its inputs and only performs the elevation + audit construction.
+     *
+     * @returns audit entry tagged `bootstrap_elevation` ready to be persisted.
+     */
+    bootstrapElevate(node, newLevel, reason) {
+        if (typeof reason !== 'string' || reason.trim().length === 0) {
+            throw new Error('bootstrapElevate requires a non-empty reason');
+        }
+        if (newLevel !== TrustLevel.VERIFIED &&
+            newLevel !== TrustLevel.ATTESTED &&
+            newLevel !== TrustLevel.TRUSTED &&
+            newLevel !== TrustLevel.PRIVILEGED) {
+            throw new Error(`bootstrapElevate target level must be VERIFIED..PRIVILEGED, got ${newLevel}`);
+        }
+        const previousLevel = node.trustLevel;
+        node.updateTrustLevel(newLevel);
+        const result = {
+            previousLevel,
+            newLevel,
+            score: 0,
+            components: { successRate: 0, uptime: 0, threatPenalty: 0, dataIntegrityScore: 0 },
+            reason: `Bootstrap elevation: ${reason}`,
+            requiresHumanApproval: false,
+        };
+        this.deps.onTrustChange?.(node.nodeId, result);
+        return {
+            tag: 'bootstrap_elevation',
+            nodeId: node.nodeId,
+            previousLevel,
+            newLevel,
+            reason: reason.trim(),
+            timestamp: new Date().toISOString(),
+            operatorBypass: true,
+        };
+    }
     recordThreatDetection(nodeId) {
         const now = new Date();
         const detections = this.threatWindows.get(nodeId) ?? [];