@glyphteck/veyl 0.71.3 → 0.73.0

package/docs/api.md

@@ -25,6 +25,8 @@ The auth and account compositions consume explicit runtime ports and have no dir
 
 Most product methods ensure login and vault unlock when saved account and vault keys are available. Long-running callers should explicitly login/unlock once and call `close()` when finished.
 
+`open({ onOperation(event) })` can observe local firebase operations, default chat/presence WebSocket frame counts, and SDK wallet-claim calls. events contain operation names, lifecycle status, counts, latency, and cache/pending-write flags; they omit payloads, document paths, account/chat IDs, and capabilities. this hook observes the default adapters, not custom cloud/live ports or server internals, and its counts are not billing units. wallet-claim observations count the SDK invocation, not Spark's internal requests. see the repository's `costs/benchmarks.md` for controlled dev scenarios and provider reconciliation.
+
 ### Local access and connectivity
 
 The shared account owner separates `localReady`, `online`, and `connection` in its snapshot. `localReady` means the exact locally signed-in account has enough encrypted bootstrap data for vault unlock; it is not server authorization. Unlock opens encrypted cached chats and wallet history without waiting for cloud services. Cached balance is display-only and must be labeled last known. `online` becomes true after cloud reads and online proof succeed; reconnect attaches services to the same unlocked session. Text sends wait up to 30 seconds for connectivity, then remain encrypted on-device as failed attempts for manual retry; reactions expire without a retry row. Avatar changes wait only for the current session, as described below. These are domain-owned pending operations, not a general cloud mutation queue. Live wallet readiness remains mandatory for payments.
@@ -174,7 +176,7 @@ await account.close();
 
 `account.peers` is the shared peer-directory owner used by Node, web, and iOS. `openAccount()` supplies its chat, wallet, blocked-user, and encrypted-cache sources directly, including missing-profile chat cleanup. Graphical adapters only subscribe to the same snapshot and profile selectors already defined by core. `openSearch('profiles')` creates profile-only search; web may also use `openSearch('mainmenu')` for its combined local-action and remote-profile menu. Active searches track peer and blocked-user changes and release those subscriptions when cleared or closed.
 
-`account.chat` is the one account-scoped protocol-v3 chat owner used by Node, web, and iOS. It owns notes/direct/group creation, stable logical chat IDs, membership epochs, encrypted list/inbox convergence, epoch-spanning history, delivery, messages, receipts, signed encrypted chat settings, member changes, leaving, and deletion. It clears every route, cache, timer, and key-bearing state on lock/account switch. Graphical providers only expose this owner through React; platform media preparation and native behavior enter through explicit ports.
+`account.chat` is the one account-scoped protocol-4 chat owner used by Node, web, and iOS. It owns notes/direct/group creation, stable logical chat IDs, membership epochs, encrypted list/inbox convergence, epoch-spanning history, delivery, messages, receipts, signed encrypted chat settings, member changes, leaving, and deletion. It clears every route, cache, timer, and key-bearing state on lock/account switch. Graphical providers only expose this owner through React; platform media preparation and native behavior enter through explicit ports.
 
 `account.wallet` is the stable account-scoped wallet composition used by Node, web, and iOS. It owns the one live `core/wallet/session.js` engine, its transfer store, cached pre-Spark display state, transaction aggregation, wallet-derived peer recency, late Spark attachment, and lock teardown. `getSnapshot()` preserves the shared `{ value, txValue }` contract; `transactions` exposes aggregate/search/chart data and `transfers` exposes focused list and keyed subscriptions. Graphical wallet providers only adapt those SDK subscriptions and add browser/native behavior through the `wallet` platform ports.
 
@@ -391,11 +393,15 @@ await veyl.chat.sendAttachment('@alice', {
 });
 
 await veyl.chat.sendAttachmentMany(['@alice', '@bob'], attachment);
-await veyl.chat.share('@alice', messageId, ['@bob']);
+await veyl.chat.forward('@alice', messageId, ['@bob']);
 const downloaded = await veyl.chat.readAttachment('@alice', messageId);
 ```
 
-The caller supplies/consumes bytes; shared owners still derive paths, encrypt/decrypt, upload/download, create message actions, and project media cache state.
+the caller supplies/consumes bytes; shared owners derive paths, encrypt/decrypt, upload/download, create message actions, and project media cache state. `chat.forward` forwards an existing attachment. forwarded attachments cannot be saved forever, and forwarding reuses the original encrypted object without extending its expiry or transmitting management authority. participants in the original conversation keep the existing save/unsave authority.
+
+audio attachment objects may include `duration` in fractional seconds and optional `waveform`: canonical padded base64 encoding of 32 unsigned bytes, representing peak-normalized rms amplitude in equal-duration bins. compact audio events expose the same validated `message.waveform`, and sharing/echoing should preserve it. generic sdk/cli uploads do not decode audio to generate it; the command schema does not accept it, and graphical clients display a stable generic waveform when it is absent. that placeholder is presentation-only and is never attached to a message as measured audio. real waveform data stays inside the encrypted message.
+
+media metadata is removed automatically before encryption, including when recognizable media is sent as a generic file. supply prepared jpeg, png, webp, gif, or supported mp4/mov/m4a bytes; video must use h.264 or hevc. normalize other image/video formats first. raw heic/avif/webm, unsupported movie tracks/codecs, and malformed media reject with `media-sanitization-failed` instead of uploading the original. orientation, color transforms, animation timing, audio/video synchronization, and display matrices are retained. this does not scrub ordinary documents, visible/audible content, or authored filenames/captions. public `account.profile.setAvatar` also sanitizes prepared webp bytes before publishing.
 
 ## Invites
 

package/docs/cli.md

@@ -117,7 +117,7 @@ Attachments use filesystem paths in the CLI while the shared owners still perfor
 ```bash
 veyl chat send-file @alice ./photo.webp --mime image/webp --caption "caption"
 veyl chat send-file-many @alice,@bob ./document.pdf --name document.pdf
-veyl chat share @alice MESSAGE_ID @bob,@carol
+veyl chat forward @alice MESSAGE_ID @bob,@carol
 veyl chat download @alice MESSAGE_ID ./downloaded-file
 ```
 

package/docs/validation.md

@@ -169,15 +169,7 @@ Cold one-off commands are inherently inefficient for agent loops because Spark b
 
 ## Server-operation cost shape
 
-The executable source is `costs/model.mjs`.
-
-Protocol v3 separates constant content cost from recipient availability cost. One visible action commits one ciphertext, one logical-chat budget update, and at most one coalesced sender owner row: 6 planning reads and 3 writes independent of group size. Each accepted recipient wake adds two route/slot reads, one minimum push-route query when APNs is due, one overwritten slot write, and one Function invocation. The default one-edge/direct upper bound is therefore 9 reads, 4 writes, and 1 invocation. Read receipts add one shared 6-read/2-write action with no wake.
-
-The current one-edge planning bundle is about 542 Firestore read-equivalent operations, 163 writes, 28 Function invocations, and one Storage Class A operation per active user/day. Headline projections are about `$2,519/month` at 100k DAU and `$25,217/month` at 1M DAU. At a sustained one visible send per second, the model is `$33.70` gross per month, or `$52.36` with one receipt per send. Set `MESSAGE_RECIPIENT_EDGES` to model larger groups; sender, wake-slot, and APNs coalescing reduce the isolated-send upper bound.
-
-Earlier live Cloud Run measurements covered the retired direct-chat delivery contract and must not be treated as v3 evidence. Current source uses anonymous opaque capability delivery, a recipient-owned overwritten slot, prompt-plus-trailing sender burst coalescing, a 250 ms slot debounce, and a 2 s APNs debounce. Dev traces must establish the real accepted-wake ratio before production projections are tightened.
-
-These totals intentionally exclude Function CPU/memory duration, outbound network, APNS delivery, Spark/vendor/network fees, media download bytes, and moderation labor until real rates are measured.
+the repository's `costs/README.md` owns cost documentation, `costs/model.mjs` owns the partial workload calculation, and `costs/dau-scale.md` contains generated projections. packaged SDK validation deliberately does not duplicate their prices or operation coefficients. source-level behavior and dated runtime samples do not establish current billing.
 
 The live L1 path confirmed that withdrawal, confirmed-UTXO discovery, claim, balance, and transfer status do not call a Veyl wallet Function or write wallet state to Firestore. They are client-local Spark SDK operations against Spark/network services. Active unlocked wallets currently run one identity-scoped deposit check every 20 seconds on REGTEST or every minute on MAINNET; a pending cooperative exit adds one exact-transfer Spark check at most every 15 seconds for ten minutes. Neither cadence is a Firebase cost. The sample consumed 2,190 sats for cooperative exit and 99 sats for the static claim, while all 3,711 recoverable sats were returned to the faucet.
 

package/examples/bot-fleet/policy.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { createVoiceRole } from './voice.js';
 
 export const BOT_FLEET_ROLES = new Set([
     'read',
@@ -7,12 +8,13 @@ export const BOT_FLEET_ROLES = new Set([
     'traffic',
     'live',
     'typing',
+    'voice',
 ]);
 const BOT_UNDERFUNDED_TEXT = 'insufficient funds';
 const ATTACHMENT_TYPES = new Set(['img', 'gif', 'm4a', 'mp4', 'file']);
 const NORMAL_CLAIM_INTERVAL_MS = 5 * 60_000;
 const FAUCET_CLAIM_INTERVAL_MS = 30_000;
-const MAX_CLAIM_BACKOFF_MS = 2 * 60_000;
+const MAX_CLAIM_BACKOFF_MS = 30 * 60_000;
 const TYPING_HEARTBEAT_MS = 2_000;
 
 function rolesFor(account) {
@@ -236,6 +238,9 @@ async function mirrorAttachment(account, client, event) {
         height: event.message.height || payload.h,
         duration: event.message.duration || payload.d,
         audio: typeof event.message.audio === 'boolean' ? event.message.audio : payload.audio,
+        ...(event.message.type === 'm4a' && event.message.waveform
+            ? { waveform: event.message.waveform }
+            : {}),
     }, {
         cid: botActionCid(event, 'echo', account),
     });
@@ -517,6 +522,7 @@ export function createBotFleetPolicy(options = {}) {
     const echoChatKeys = new Set();
     const claimStates = new Map();
     const liveStates = new Map();
+    const voiceStates = new Map();
 
     function shouldMirror(account, event) {
         if (isFleetGeneratedMessage(event)) return false;
@@ -588,9 +594,22 @@ export function createBotFleetPolicy(options = {}) {
                 if (roles.has('live')) {
                     await startLiveRole(account, client, liveStates);
                 }
+                if (roles.has('voice')) {
+                    const voice = createVoiceRole(client, current.uid);
+                    voiceStates.set(account.profile, voice);
+                    try { await voice.start(); }
+                    catch (error) {
+                        voiceStates.delete(account.profile);
+                        await voice.close();
+                        throw error;
+                    }
+                }
             }
         },
         async stop({ account }) {
+            const voice = voiceStates.get(account.profile);
+            voiceStates.delete(account.profile);
+            await voice?.close();
             await stopLiveRole(account, liveStates);
             await stopClaimLoop(account.profile, claimStates);
             const username = usernameByProfile.get(account.profile);
@@ -602,6 +621,8 @@ export function createBotFleetPolicy(options = {}) {
             if (username) managedUsernames.delete(username);
         },
         async stopFleet() {
+            await Promise.all([...voiceStates.values()].map(voice => voice.close()));
+            voiceStates.clear();
             await Promise.all([...liveStates.keys()].map((profile) =>
                 stopLiveRole({ profile, roles: [] }, liveStates)
             ));

package/examples/bot-fleet/readme.md

@@ -12,6 +12,7 @@ The secret-free version-2 manifest stores account indices, usernames, networks,
 - `traffic` is an eligibility marker for an external local operator policy; it performs no work by itself.
 - `live` holds the account's normal encrypted live-room connection in each chat without advancing read state or sending messages. The concrete host supplies the same realm-matched portable live transport used by graphical clients; startup rejects this role when that client port is absent.
 - `typing` requires `live` and continually renews one stable composition through the same encrypted live state until the policy stops.
+- `voice` starts muted and joins the newest active, foreign-occupied call among the account's watched chats. It uses `client.chat.watch(onChats, { count: 500 })`, `client.calls.observe(chatId, onAvailable)`, and strict `joinExisting(chatId, callId)`; it never creates a call or inherits read/echo behavior. The host must supply real `calls.media` and ephemeral `calls.mls` ports. One shared owner admits the new destination before leaving an old call, supports cancellation, and leaves when no other account remains. A failed unchanged room is not retried on every heartbeat.
 
 Only response-capable fleet peers are loop-suppressed. Incoming transaction events and staggered fallback loops call the public wallet claim method. Startup replays a bounded visible window; an event checkpoint suppresses completed source messages, while the action journal suppresses completed effects and stops ambiguous payments for explicit reconciliation.
 

package/examples/bot-fleet/runtime.js

@@ -24,6 +24,13 @@ export async function resolveBotFleetClientOptions(source, profile) {
     ) {
         throw new Error(`live bot transport required: ${profile.profile}`);
     }
+    if (profile?.roles?.includes('voice') && (
+        typeof options?.calls?.media?.open !== 'function'
+        || typeof options?.calls?.media?.prepare !== 'function'
+        || typeof options?.calls?.mls?.createMember !== 'function'
+    )) {
+        throw new Error(`voice bot media and encryption ports required: ${profile.profile}`);
+    }
     return options;
 }
 
@@ -41,7 +48,7 @@ export async function createExampleBotFleetRuntime(options = {}) {
         policies: [],
         eventOptions: async (profile) => ({
             replay: true,
-            chats: profile.roles.includes('read') || profile.roles.includes('live'),
+            chats: profile.roles.some(role => ['read', 'live', 'voice'].includes(role)),
             persistentChats: true,
             persistentChatIdleMs: options.persistentChatIdleMs || 5 * 60_000,
             transactions: true,

package/examples/bot-fleet/voice.js

@@ -0,0 +1,157 @@
+function sameRoom(left, right) {
+    return !!left && !!right
+        && left.chatId === right.chatId && left.callId === right.callId;
+}
+
+function availableRoom(value, chatId, uid) {
+    if (value?.chatId !== chatId || !value.callId || !Number.isFinite(value.startedAt)) return null;
+    const others = (value.roster || []).filter(peer => peer.uid && peer.uid !== uid);
+    if (!others.length) return null;
+    // Own admission and audio preferences do not constitute a new opportunity
+    // to retry a failed room. Only a new call or changed foreign membership does.
+    const members = others.map(peer => [peer.uid, peer.chatPK, peer.holder]).sort();
+    return {
+        chatId, callId: value.callId, startedAt: value.startedAt,
+        fingerprint: JSON.stringify([value.callId, value.startedAt, members]),
+    };
+}
+
+export function createVoiceRole(client, uid) {
+    if (!uid) throw new Error('voice bot account identity required');
+    const calls = client.calls;
+    const chats = new Map();
+    let closed = false;
+    let dirty = false;
+    let running = null;
+    let startup = null;
+    let stopping = null;
+    let pending = null;
+    let releaseChats = null;
+    let releaseCalls = null;
+    let lastError = null;
+
+    function report(error) {
+        const code = /^[a-z0-9/-]{1,80}$/u.test(error?.code || '') ? error.code : 'calls/failed';
+        client.diag?.('bot.voice.error', { code });
+    }
+
+    function newest() {
+        let selected = null;
+        for (const entry of chats.values()) {
+            const room = entry.room;
+            if (!room || entry.failed === room.fingerprint) continue;
+            if (!selected || room.startedAt > selected.startedAt
+                || (room.startedAt === selected.startedAt && room.chatId > selected.chatId)) selected = room;
+        }
+        return selected;
+    }
+
+    function fail(room, error) {
+        const entry = chats.get(room?.chatId);
+        if (sameRoom(entry?.room, room)) entry.failed = entry.room.fingerprint;
+        if (error?.code !== 'calls/cancelled') report(error);
+    }
+
+    async function reconcile() {
+        const room = newest();
+        const current = calls.getSnapshot();
+        if (!room) {
+            if (current.joiningChatId || !['idle', 'error'].includes(current.phase)) await calls.leave();
+            return;
+        }
+        // callId identifies the admitted instance even while ICE is joining or
+        // waiting. Only joiningChatId represents an unadmitted candidate.
+        if (sameRoom(current, room) && !['idle', 'error'].includes(current.phase)) return;
+        const attempt = { ...room, cancelled: false };
+        pending = attempt;
+        try {
+            // The shared owner admits the destination before retiring an
+            // existing call. A stale discovery can never create a fresh call.
+            await calls.joinExisting(room.chatId, room.callId);
+        } catch (error) {
+            if (!closed && !attempt.cancelled) fail(room, error);
+        } finally {
+            if (pending === attempt) pending = null;
+            dirty = true;
+        }
+    }
+
+    function changed() {
+        if (closed) return;
+        dirty = true;
+        if (pending && !pending.cancelled && !sameRoom(pending, newest())) {
+            pending.cancelled = true;
+            void calls.cancelJoin().catch(report);
+        }
+        if (running) return;
+        running = Promise.resolve().then(async () => {
+            while (dirty && !closed) {
+                dirty = false;
+                await reconcile();
+            }
+        }).catch(report).finally(() => {
+            running = null;
+            if (dirty && !closed) changed();
+        });
+    }
+
+    function syncChats(values) {
+        if (closed) return;
+        const ids = new Set(values.filter(chat => !chat.messageRequest && !chat.membershipRemoved).map(chat => chat.id));
+        for (const [chatId, entry] of chats) {
+            if (ids.has(chatId)) continue;
+            chats.delete(chatId);
+            entry.release();
+        }
+        for (const chatId of ids) {
+            if (chats.has(chatId)) continue;
+            const entry = { room: null, failed: null, release: () => {} };
+            chats.set(chatId, entry);
+            entry.release = calls.observe(chatId, value => {
+                if (closed || chats.get(chatId) !== entry) return;
+                const room = availableRoom(value, chatId, uid);
+                if (entry.room?.fingerprint === room?.fingerprint) return;
+                entry.room = room;
+                entry.failed = null;
+                changed();
+            });
+        }
+        changed();
+    }
+
+    return Object.freeze({
+        start() {
+            startup ||= (async () => {
+                await calls.setMuted(true);
+                if (closed) return;
+                releaseCalls = calls.subscribe(() => {
+                    const { error } = calls.getSnapshot();
+                    if (error && error !== lastError && error.code !== 'calls/cancelled') {
+                        lastError = error;
+                        const entry = chats.get(error.chatId);
+                        if (entry?.room) entry.failed = entry.room.fingerprint;
+                        report(error);
+                    }
+                    changed();
+                });
+                const release = await client.chat.watch(syncChats, { count: 500 });
+                if (closed) release();
+                else releaseChats = release;
+            })();
+            return startup;
+        },
+        close() {
+            if (stopping) return stopping;
+            closed = true;
+            releaseCalls?.();
+            releaseChats?.();
+            for (const entry of chats.values()) entry.release();
+            chats.clear();
+            // leave synchronously revokes local playback/join intent. A late
+            // watch setup or old join completion cannot retain this role.
+            const leaving = calls.leave();
+            stopping = Promise.allSettled([startup, running, leaving]).then(() => undefined);
+            return stopping;
+        },
+    });
+}

package/package.json

@@ -25,6 +25,7 @@
         "examples/bot-fleet/index.js",
         "examples/bot-fleet/policy.js",
         "examples/bot-fleet/runtime.js",
+        "examples/bot-fleet/voice.js",
         "examples/bot-fleet/readme.md",
         "examples/codex-agent/agent-instructions.js",
         "examples/codex-agent/agent-state.js",
@@ -53,5 +54,5 @@
         "start": "node src/cli.js",
         "lint": "eslint src --quiet"
     },
-    "version": "0.71.3"
+    "version": "0.73.0"
 }