The Notes voice API accepts a short native recording and returns an actor-owned
job. Native Notes exposes recording from its list, using the existing persistent
shell dock rather than mounting another navbar. Recording remains local until the
user pauses and explicitly chooses transcription/analysis, with a personal-credit
notice. Pause, resume, retake and cancel remain in the same dock; backgrounding
pauses recording, and account/workspace changes or leaving Notes discard unsent
recording bytes. Existing Notes editing and locking remain unchanged.
Completed results use a compact review sheet with transcript, summary, decisions,
proposed actions, recommendations and evidence. A successful transcript can also
be reviewed/saved if the later analysis has a known failure. Save note to this
workspace is explicit: private results become an ordinary workspace Note, which
may be visible to team members. Saving creates no task or event. The voice job UUID
is the stable Note ID, so retrying a save does not duplicate the note or overwrite
later user edits. Users can edit the saved note through the existing editor.
Only the stable job intent is persisted before dispatch, so navigation can recover
a submitted job without persisting its audio. The latest authorized job is cached
under its actor/workspace, shown immediately on return and revalidated even when
fresh. Transport, 429/5xx and MFA challenges
retain that scoped result; definitive access loss/not-found removes it. Old async
responses are fenced across account/workspace away-and-back transitions. Deleting a job disables new capture until the request completes. Definitive
DELETE access loss/not-found clears the scoped result; MFA and temporary failures
retain it. Cached result deletion rechecks ownership after initialization and queue admission; once
admitted, the serialized snapshot and index purge completes before new publication. Temporary
status failures offer explicit retry; ongoing successful status requests poll only
while Notes is active. In-memory recording bytes permit explicit safe preflight
retries using the same request ID/revision. After navigation discards those bytes,
users can retain a successful transcript or record again; paid uncertain jobs
never automatically restart.
Input is mono 16 kHz PCM16 WAV, at most 120 seconds. The server verifies actual
frames and bounds streamed multipart bytes rather than trusting a claimed duration.
Audio bytes are transient and are not stored in job rows or billing metadata.
Transcription and structured analysis use the requesting user’s personal AI
credits. Results include a transcript, summary, supported decisions, action items,
recommendations with evidence, and open questions. These are proposals for review;
the API creates no Notes documents, tasks, Calendar events, or room-shared artifacts.
Transcripts are untrusted input, including spoken instructions. Unknown owners and
deadlines remain unspecified. Silence does not trigger a second analysis request.
Jobs and artifacts are private to the requesting actor, even in team workspaces.
Every status read, creation, retry, and deletion verifies current workspace access.
Definitive loss of access denies retained artifacts. Workspace/account deletion
cascades job deletion; completed or stopped jobs can be explicitly deleted through
the job endpoint. Processing jobs must finish or enter review before deletion.
A stable request ID plus audio/time-zone digest deduplicates creation. Changed
payloads conflict. Atomic revision claims prevent duplicate provider execution.
Known preflight failures require an explicit retry against the current revision;
a successful transcript is reused when only analysis needs retry. Provider or
settlement outcomes without reliable accounting enter review required rather
than being automatically replayed or assigned an invented charge/refund.
Processing runs in a bounded Next response-tail callback. Persisted status is
recoverable after client navigation; the callback is not a durable execution queue.
Interrupted or abandoned work is marked for review after its execution window.
Clients must not automatically resubmit review-required jobs.
Regression coverage: notes-voice/audio.test.ts, jobs.test.ts, provider.test.ts,
request.test.ts, the internal API client tests, and note-voice-jobs.sql cover
input limits, metering, actor isolation, revision/retry behavior and RLS. API routes
are first-class Next handlers tracked as Rust migration backlog. Native cubit,
repository and widget regressions cover owner transitions, retry intents, retained
snapshots, denied access, real recording controls, enlarged-text review and explicit
stable-ID saves. cache_store_scoped_removal_test.dart covers obsolete deletions
waiting for initialization/admission and durable denied-history erasure. Device
microphone/provider execution and production deployment
remain separate runtime verification gates.
