@antiphony/shared 0.3.0 → 0.5.0

package/dist/esm/chunk-TVOXIQKF.js

@@ -0,0 +1,294 @@
+import { FirestoreTimestampSchema } from './chunk-D655OH2I.js';
+import { BlobRefSchema } from './chunk-SMK4OZNU.js';
+import { z } from 'zod';
+
+var ProcessingStageStatusSchema = z.enum(["pending", "ready", "failed", "skipped"]);
+var PROCESSING_STAGES = ["denoise", "trim", "transcribe", "waveform"];
+var ProcessingStageSchema = z.enum(PROCESSING_STAGES);
+var BYTE_MUTATING_STAGES = ["denoise", "trim"];
+var DERIVED_STAGES = ["transcribe", "waveform"];
+var ProcessingRequestSchema = z.object({
+  transcribe: z.boolean().optional(),
+  denoise: z.boolean().optional(),
+  trim: z.boolean().optional(),
+  waveform: z.boolean().optional(),
+  /**
+   * Whether a completed byte-mutating stage should invalidate and recompute
+   * the derived artifacts that describe the old audio. Defaults to **true**
+   * — a transcript of superseded audio is wrong, not merely stale.
+   *
+   * `false` opts out, for an app that would rather keep the existing
+   * transcript than pay to regenerate it. It does NOT name a stage, so a
+   * request carrying only `reprocess` requests no work.
+   */
+  reprocess: z.boolean().optional()
+});
+var ProcessingStageMapSchema = z.object({
+  transcribe: ProcessingStageStatusSchema.optional(),
+  denoise: ProcessingStageStatusSchema.optional(),
+  trim: ProcessingStageStatusSchema.optional(),
+  waveform: ProcessingStageStatusSchema.optional()
+});
+var ResolvedProcessingSchema = ProcessingStageMapSchema.extend({
+  reprocess: z.boolean().optional()
+});
+var ProcessingStateSchema = ResolvedProcessingSchema.extend({
+  /**
+   * Content CID of the processed audio variant — the composed output of every
+   * byte-mutating stage that has completed. The record's own
+   * `embed.audio.ref.$link` stays the ORIGINAL CID (immutable content
+   * address); only the read-time view swaps playback to this variant.
+   */
+  processedBlobCid: z.string().optional(),
+  /**
+   * MIME type of the processed variant. Present because providers may
+   * TRANSCODE — the ElevenLabs Voice Isolator returns MP3 regardless of what
+   * it is given — so the variant's type cannot be assumed to match
+   * `embed.audio.mimeType`. Anything reading the variant's bytes must use
+   * this, not the embed's.
+   */
+  processedMimeType: z.string().optional(),
+  /**
+   * Duration of the processed variant, when a byte-mutating stage changed it
+   * (i.e. trim). Absent when the variant's duration matches the original.
+   */
+  processedDurationMs: z.number().int().min(0).optional(),
+  /**
+   * Peaks for the processed variant, once the `waveform` stage completes.
+   * Same normalization and bounds as `embed.waveform` (0–100, max 1000), so
+   * a view can never carry a larger payload than the record allows.
+   */
+  waveformPeaks: z.array(z.number().int().min(0).max(100)).max(1e3).optional(),
+  /**
+   * When the current runner's exclusive claim on this post expires.
+   *
+   * Queue delivery is at-least-once, so the same job can arrive twice and
+   * run CONCURRENTLY. `process()` is idempotent under sequential retry — it
+   * acts on `pending` and re-does nothing already settled — but two passes
+   * interleaved is a different failure: both read the same `pending` state,
+   * both bill the provider for the same stage, and both write
+   * `processedBlobCid`, so the surviving variant is whichever finished last
+   * and the other's blob is orphaned.
+   *
+   * A runner claims this field transactionally before doing any work and
+   * clears it when finished; a second runner finding it unexpired declines
+   * and returns. It is an EXPIRY, not a boolean lock, because the holder can
+   * die mid-run (instance recycled, process killed) with no chance to
+   * release — a plain flag would strand the post permanently, where a lapsed
+   * lease lets the next delivery pick it up.
+   *
+   * Internal, like the variant fields above: `toProcessingView` projects
+   * stages only, so this never reaches a client.
+   */
+  leaseUntil: FirestoreTimestampSchema.optional(),
+  updatedAt: FirestoreTimestampSchema
+});
+var ProcessingViewSchema = ProcessingStageMapSchema;
+function toProcessingView(state) {
+  const view = {};
+  for (const stage of PROCESSING_STAGES) {
+    if (state[stage] !== void 0) view[stage] = state[stage];
+  }
+  return view;
+}
+function resolveAudioVariant(canonical, state) {
+  var _a;
+  if (!state) return canonical;
+  const hasVariant = state.processedBlobCid !== void 0;
+  const peaksAreCurrent = state.waveform === "ready" && state.waveformPeaks !== void 0;
+  return {
+    blobCid: hasVariant ? state.processedBlobCid : canonical.blobCid,
+    durationMs: hasVariant ? (_a = state.processedDurationMs) != null ? _a : canonical.durationMs : canonical.durationMs,
+    waveform: peaksAreCurrent ? state.waveformPeaks : canonical.waveform
+  };
+}
+
+// types/audio.ts
+var StrongRefSchema = z.object({
+  uri: z.string().regex(/^at:\/\/.+/, "Must be an at:// URI"),
+  cid: z.string()
+});
+var ReplyRefSchema = z.object({
+  root: StrongRefSchema,
+  parent: StrongRefSchema
+});
+var AudioEmbedSchema = z.object({
+  $type: z.literal("dev.antiphony.embed.audio"),
+  /** The audio bytes as a content-addressed blob ref (`ref.$link` = CID). */
+  audio: BlobRefSchema,
+  /** Duration in MILLISECONDS (platform-wide unit; not seconds). */
+  durationMs: z.number().int().min(0).optional(),
+  /** User-authored short description (audio analogue of image alt). NOT the transcript. */
+  alt: z.string().max(1e4).optional(),
+  /** Pre-computed waveform peaks (normalized 0–100) for instant rendering. */
+  waveform: z.array(z.number().int().min(0).max(100)).max(1e3).optional()
+});
+var TranscriptSegmentSchema = z.object({
+  startMs: z.number().int().min(0),
+  endMs: z.number().int().min(0),
+  text: z.string()
+}).refine((s) => s.endMs >= s.startMs, {
+  message: "endMs must be >= startMs",
+  path: ["endMs"]
+});
+var TimedTranscriptSchema = z.object({
+  segments: z.array(TranscriptSegmentSchema),
+  text: z.string().optional()
+});
+var AudioEmbedViewSchema = z.object({
+  $type: z.literal("dev.antiphony.embed.audio#view"),
+  /**
+   * `url`, `durationMs` and `waveform` are RESOLVED, not copied: once
+   * processing has produced an audio variant they describe that variant
+   * rather than the bytes the client uploaded. They always agree with one
+   * another — a duration and a set of peaks are only meaningful against the
+   * audio `url` actually points at.
+   *
+   * A client that stored `durationMs` at upload time should therefore expect
+   * it to change (trim removes leading/trailing silence), and should render
+   * these three as a set rather than caching them independently. The record's
+   * originals are immutable and unaffected; this is a read-time resolution.
+   */
+  url: z.string().url(),
+  durationMs: z.number().int().min(0).optional(),
+  // `alt` is copied from the stored embed; keep the same bounds so a view can
+  // never carry a larger payload than the record allows.
+  alt: z.string().max(1e4).optional(),
+  waveform: z.array(z.number().int().min(0).max(100)).max(1e3).optional(),
+  /** Lifted from the transcript enrichment record; absent until transcription completes. */
+  transcript: TimedTranscriptSchema.optional(),
+  /**
+   * Per-stage audio-processing status (denoise / trim / transcribe /
+   * waveform), when the app opted into processing. Absent otherwise. A
+   * `pending` stage means the client should poll (or re-render) for the
+   * result — including a stage that returns to `pending` after having been
+   * `ready`, which is how a recompute surfaces. Once a byte-mutating stage
+   * completes, `url`/`durationMs`/`waveform` above already resolve to the
+   * processed audio variant. See `types/processing.ts`.
+   */
+  processing: ProcessingViewSchema.optional()
+});
+var AudioPostRecordSchema = z.object({
+  /** Storage id (rkey/doc id). */
+  id: z.string(),
+  /**
+   * Content CID of the canonical lexicon record (CIDv1, dag-cbor, sha2-256
+   * — the AT Protocol record-CID rule). Computed at write time over the
+   * lexicon projection (public fields only, NOT the storage/tenancy fields
+   * below), so StrongRefs built from it are verifiable content addresses.
+   */
+  cid: z.string(),
+  // --- Tenancy + facets (storage-indexed; NOT in the lexicon) ---
+  /** Origin app that created this record — the multi-tenant isolation key. */
+  originAppId: z.string(),
+  /** Authoring user. A queryable facet, not the tenancy boundary. */
+  authorId: z.string(),
+  /** Optional AT Protocol identity of the author (facet). */
+  authorDid: z.string().optional(),
+  /** Optional org context (facet). */
+  orgId: z.string().nullable().optional(),
+  /** Denormalized from `reply` presence: `reply` set ⇒ 'reply', else 'prompt'. */
+  kind: z.enum(["prompt", "reply"]),
+  /**
+   * Branch participant pair (author ids) for reply gating — the parties to a
+   * reply's sub-thread: the creator (thread-root author) + the responder who
+   * opened the branch. Set on replies (deduped, 1–2 ids); absent on prompts
+   * (a prompt's repliers are the app's audience policy, not a fixed pair).
+   * Inherited down the branch so reply gating is an O(1) field check, never a
+   * thread walk.
+   */
+  threadParticipants: z.array(z.string()).optional(),
+  /**
+   * Author of this reply's thread ROOT (the prompt) — the reply's recipient,
+   * the person whose "replies to me" feed it lands in. Denormalized at write
+   * time so "replies whose root author is X" is a cheap composite-index query
+   * (see `queryByRootAuthor`). Set on replies (`kind === 'reply'`); absent on
+   * prompts. Storage-layer facet, NOT in the public lexicon or the record CID.
+   */
+  rootAuthorId: z.string().optional(),
+  /**
+   * Async audio-processing state (transcribe / denoise), present iff the app
+   * opted into processing on create. Mutated by the processing worker after
+   * the post is created — storage-layer, NOT in the lexicon or the record
+   * CID. See `types/processing.ts`.
+   */
+  processing: ProcessingStateSchema.optional(),
+  // --- Lexicon fields (public contract) ---
+  /** User-authored text (bsky-semantic). May be empty for pure-audio posts. NEVER the transcript. */
+  text: z.string().max(3e3),
+  /** Optional headline; a prompt feature, not the discriminator. */
+  title: z.string().max(3e3).optional(),
+  /** Audio (or other) attachment. Audio posts carry an `AudioEmbed`. */
+  embed: AudioEmbedSchema.optional(),
+  /** Present iff this post is a reply (StrongRef root + parent). */
+  reply: ReplyRefSchema.optional(),
+  /** BCP-47 language tags for the text. */
+  langs: z.array(z.string()).max(3).optional(),
+  /** Author-applied self-label values (content warnings). Simplified from the
+   *  lexicon's `com.atproto.label.defs#selfLabels` to the bare value strings. */
+  selfLabels: z.array(z.string()).optional(),
+  createdAt: FirestoreTimestampSchema
+}).refine(
+  // `kind` is denormalized from `reply` presence at write time; enforce the
+  // invariant so an inconsistent record can't be written or read silently.
+  // A reply has `reply`, no `title`, and a stamped `rootAuthorId` (its
+  // recipient facet); a prompt has none of those.
+  (r) => r.kind === "reply" ? !!r.reply && r.title === void 0 && r.rootAuthorId !== void 0 : !r.reply && r.rootAuthorId === void 0,
+  {
+    message: "kind must match reply presence: 'reply' \u21D2 reply set, no title, rootAuthorId set; 'prompt' \u21D2 no reply, no rootAuthorId",
+    path: ["kind"]
+  }
+);
+var TranscriptEnrichmentRecordSchema = z.object({
+  id: z.string(),
+  /** The post whose audio this transcribes. */
+  subject: StrongRefSchema,
+  transcript: TimedTranscriptSchema,
+  /** BCP-47 language tag of the transcript. */
+  lang: z.string().optional(),
+  /** Model/provider provenance (the generator is a pluggable port). */
+  model: z.string().optional(),
+  createdAt: FirestoreTimestampSchema
+});
+var ActorProfileRecordSchema = z.object({
+  handle: z.string().min(3).max(20).optional(),
+  usageIntent: z.string().max(100).optional(),
+  rssFeed: z.string().url().optional()
+});
+var ViewerStateSchema = z.object({
+  /** True when the authenticated caller authored this post. */
+  isAuthor: z.boolean().default(false),
+  /**
+   * Whether the caller may reply to this post (reply gating, §6). A prompt is
+   * repliable by any authenticated viewer (the app's audience-policy default);
+   * a reply only by its branch participants (`{ creator, branch responder }`).
+   */
+  canReply: z.boolean().default(false),
+  /** Why `canReply` is false, when it is (omitted when the caller can reply). */
+  replyDisabledReason: z.enum(["unauthenticated", "not_a_participant"]).optional()
+});
+var PostRecordPublicSchema = z.object({
+  text: z.string(),
+  title: z.string().optional(),
+  reply: ReplyRefSchema.optional(),
+  langs: z.array(z.string()).optional(),
+  selfLabels: z.array(z.string()).optional(),
+  createdAt: FirestoreTimestampSchema
+});
+var AudioPostViewSchema = z.object({
+  /** at:// URI (or internal ref) identifying the post. */
+  uri: z.string(),
+  /** Content CID of the canonical record (see `AudioPostRecordSchema.cid`). */
+  cid: z.string(),
+  kind: z.enum(["prompt", "reply"]),
+  /** The acting actor's app-scoped id — an opaque attribution ref, not a profile. */
+  authorId: z.string(),
+  /** The author's app-asserted AT Protocol DID, when the caller provided one. */
+  authorDid: z.string().optional(),
+  record: PostRecordPublicSchema,
+  /** Hydrated audio embed (signed URL + lifted transcript). */
+  embed: AudioEmbedViewSchema.optional(),
+  viewer: ViewerStateSchema
+});
+
+export { ActorProfileRecordSchema, AudioEmbedSchema, AudioEmbedViewSchema, AudioPostRecordSchema, AudioPostViewSchema, BYTE_MUTATING_STAGES, DERIVED_STAGES, PROCESSING_STAGES, PostRecordPublicSchema, ProcessingRequestSchema, ProcessingStageMapSchema, ProcessingStageSchema, ProcessingStageStatusSchema, ProcessingStateSchema, ProcessingViewSchema, ReplyRefSchema, ResolvedProcessingSchema, StrongRefSchema, TimedTranscriptSchema, TranscriptEnrichmentRecordSchema, TranscriptSegmentSchema, ViewerStateSchema, resolveAudioVariant, toProcessingView };

package/dist/esm/index.d.ts

@@ -1,11 +1,314 @@
-export { CreateAudioPostRequest, CreateAudioPostRequestSchema, UpdateProfileRequestSchema } from './api-codecs.js';
-export { FirestoreTimestamp, FirestoreTimestampSchema, UserRecord, UserRecordSchema, httpsUrl } from './types/records.js';
-export { ProfileView, ProfileViewAdmin, ProfileViewAdminSchema, ProfileViewBasic, ProfileViewBasicSchema, ProfileViewDetailed, ProfileViewDetailedSchema, ProfileViewSchema, ProfileViewSelf, ProfileViewSelfSchema, toProfileViewBasic } from './types/views.js';
+export { CreateAudioPostRequest, CreateAudioPostRequestSchema, PatchAudioPostRequest, PatchAudioPostRequestSchema } from './api-codecs.js';
+export { FirestoreTimestamp, FirestoreTimestampSchema } from './types/records.js';
 export { ActorProfileRecord, ActorProfileRecordSchema, AudioEmbed, AudioEmbedSchema, AudioEmbedView, AudioEmbedViewSchema, AudioPostRecord, AudioPostRecordSchema, AudioPostView, AudioPostViewSchema, PostRecordPublic, PostRecordPublicSchema, ReplyRef, ReplyRefSchema, StrongRef, StrongRefSchema, TimedTranscript, TimedTranscriptSchema, TranscriptEnrichmentRecord, TranscriptEnrichmentRecordSchema, TranscriptSegment, TranscriptSegmentSchema, ViewerState, ViewerStateSchema } from './types/audio.js';
-export { BlobRef, BlobRefSchema, resolveAudioUrl } from './types/blob.js';
-export { ActorView, ActorViewSchema, PublicProfileDto, PublicProfileDtoSchema } from './types/api.js';
-export { COLLECTIONS, EMBED_NSID, NSID, NsidValue, nsidForCollection } from './nsid.js';
+import { z } from 'zod';
+export { BlobRef, BlobRefSchema } from './types/blob.js';
+export { COLLECTIONS, EMBED_NSID, NSID, NsidValue, StoredNsidValue } from './nsid.js';
 export { ConflictError, ForbiddenError, NotFoundError, RateLimitError, ServiceError, UnauthorizedError, ValidationError } from './errors/index.js';
 export { isFirestoreTimestamp } from './utils/index.js';
 export { ReportedErrorEvent, buildReportedErrorEvent, reportError } from './observability/report-error.js';
-import 'zod';
+
+/**
+ * Audio hygiene / enrichment processing (B5).
+ *
+ * Antiphony can, when the calling app opts in, run audio processing on a
+ * post's audio. Four stages, classified on two axes (see
+ * `specs/enrichment-pipeline.md`):
+ *
+ *  - **Byte-mutating** (`denoise`, `trim`) produce new audio. They compose in
+ *    order into a SINGLE processed variant — trimmed-and-denoised audio is one
+ *    artifact, not two — addressed by `processedBlobCid`.
+ *  - **Derived** (`transcribe`, `waveform`) are pure analysis over the final
+ *    variant and modify no audio. Because they are a function of the variant,
+ *    recomputation is always the correct response to their input changing.
+ *
+ * Every stage is OFF by default — the app asks for them per post via
+ * `CreateAudioPostRequest.processing`, or after the fact via the `processing`
+ * opt-in on `PATCH /api/v1/posts/{postId}`.
+ *
+ * The work runs asynchronously (outside the create request), so a post
+ * carries a mutable `processing` state that starts `pending` and settles to
+ * `ready`/`failed`/`skipped` per stage. That state is a storage-layer field —
+ * it is NOT part of the canonical lexicon record and never enters the record
+ * CID (like `kind` and `threadParticipants`), so processing can update it
+ * without changing the post's content address.
+ *
+ * That immutability is why stage OUTPUT lives here rather than on the embed:
+ * `embed.audio.ref.$link`, `embed.durationMs`, and `embed.waveform` are inside
+ * the CID and can never be rewritten. The read-time view resolves per field
+ * between the record's canonical values and the variant values below.
+ */
+/**
+ * Per-stage status.
+ *  - `pending`  — requested, not yet done (the worker acts on these).
+ *  - `ready`    — completed.
+ *  - `failed`   — attempted and errored.
+ *  - `skipped`  — requested but this deployment has no provider for it.
+ *
+ * A stage returning to `pending` after having been `ready` is NORMAL, not a
+ * regression: a byte-mutating stage completing invalidates derived artifacts,
+ * which are then recomputed. Clients treat any `pending` stage as "still
+ * working", which already covers this.
+ */
+declare const ProcessingStageStatusSchema: z.ZodEnum<["pending", "ready", "failed", "skipped"]>;
+type ProcessingStageStatus = z.infer<typeof ProcessingStageStatusSchema>;
+/**
+ * The stage names, in the order a multi-stage request runs them:
+ * denoise → trim → (transcribe, waveform).
+ *
+ * All byte-mutating stages run first; the two derived stages then consume the
+ * final variant and are mutually independent. Denoise precedes trim
+ * deliberately — silence detection keys off a noise floor, so on noisy input
+ * the "silence" is not actually quiet and trim under-cuts.
+ */
+declare const PROCESSING_STAGES: readonly ["denoise", "trim", "transcribe", "waveform"];
+declare const ProcessingStageSchema: z.ZodEnum<["denoise", "trim", "transcribe", "waveform"]>;
+type ProcessingStage = z.infer<typeof ProcessingStageSchema>;
+/** Stages that produce new audio bytes, composing into one processed variant. */
+declare const BYTE_MUTATING_STAGES: readonly ["denoise", "trim"];
+/** Stages that are pure analysis over the final variant, modifying no audio. */
+declare const DERIVED_STAGES: readonly ["transcribe", "waveform"];
+/**
+ * What the calling app opts into, on `CreateAudioPostRequest`. All default
+ * off; only `true` values request a stage.
+ */
+declare const ProcessingRequestSchema: z.ZodObject<{
+    transcribe: z.ZodOptional<z.ZodBoolean>;
+    denoise: z.ZodOptional<z.ZodBoolean>;
+    trim: z.ZodOptional<z.ZodBoolean>;
+    waveform: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Whether a completed byte-mutating stage should invalidate and recompute
+     * the derived artifacts that describe the old audio. Defaults to **true**
+     * — a transcript of superseded audio is wrong, not merely stale.
+     *
+     * `false` opts out, for an app that would rather keep the existing
+     * transcript than pay to regenerate it. It does NOT name a stage, so a
+     * request carrying only `reprocess` requests no work.
+     */
+    reprocess: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    denoise?: boolean | undefined;
+    trim?: boolean | undefined;
+    transcribe?: boolean | undefined;
+    waveform?: boolean | undefined;
+    reprocess?: boolean | undefined;
+}, {
+    denoise?: boolean | undefined;
+    trim?: boolean | undefined;
+    transcribe?: boolean | undefined;
+    waveform?: boolean | undefined;
+    reprocess?: boolean | undefined;
+}>;
+type ProcessingRequest = z.infer<typeof ProcessingRequestSchema>;
+/**
+ * Per-stage status across all stages — the shape shared by the stored state,
+ * the hydrated view, and the resolved-initial-state handoff between the route
+ * and the service. A key is present iff that stage was requested.
+ */
+declare const ProcessingStageMapSchema: z.ZodObject<{
+    transcribe: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    denoise: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    trim: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    waveform: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+}, "strip", z.ZodTypeAny, {
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+}, {
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+}>;
+type ProcessingStageMap = z.infer<typeof ProcessingStageMapSchema>;
+/**
+ * An opt-in request resolved against a deployment's capabilities: the initial
+ * per-stage state plus the settings the async worker needs to honour it.
+ *
+ * `reprocess` is carried here — and persisted — rather than passed to the
+ * worker as an argument, because the request that asks for the work and the
+ * pass that performs it are separated by a queue (step 8). Written on every
+ * request including the default, because the stored state is MERGED onto —
+ * absent means true only for posts written before this field existed.
+ */
+declare const ResolvedProcessingSchema: z.ZodObject<{
+    transcribe: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    denoise: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    trim: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    waveform: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+} & {
+    reprocess: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    reprocess?: boolean | undefined;
+}, {
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    reprocess?: boolean | undefined;
+}>;
+type ResolvedProcessing = z.infer<typeof ResolvedProcessingSchema>;
+/**
+ * Stored processing state on the post record (storage-layer; not in the CID):
+ * the per-stage statuses plus the output of the stages themselves.
+ *
+ * The variant fields below all exist for the same reason — their canonical
+ * counterparts live inside the record CID and cannot be updated:
+ *
+ *  - `processedBlobCid` ↔ `embed.audio.ref.$link`
+ *  - `processedMimeType` ↔ `embed.audio.mimeType` (providers may transcode)
+ *  - `processedDurationMs` ↔ `embed.durationMs` (trim changes duration)
+ *  - `waveformPeaks` ↔ `embed.waveform` (the client's peaks describe the original)
+ */
+declare const ProcessingStateSchema: z.ZodObject<{
+    transcribe: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    denoise: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    trim: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    waveform: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+} & {
+    reprocess: z.ZodOptional<z.ZodBoolean>;
+} & {
+    /**
+     * Content CID of the processed audio variant — the composed output of every
+     * byte-mutating stage that has completed. The record's own
+     * `embed.audio.ref.$link` stays the ORIGINAL CID (immutable content
+     * address); only the read-time view swaps playback to this variant.
+     */
+    processedBlobCid: z.ZodOptional<z.ZodString>;
+    /**
+     * MIME type of the processed variant. Present because providers may
+     * TRANSCODE — the ElevenLabs Voice Isolator returns MP3 regardless of what
+     * it is given — so the variant's type cannot be assumed to match
+     * `embed.audio.mimeType`. Anything reading the variant's bytes must use
+     * this, not the embed's.
+     */
+    processedMimeType: z.ZodOptional<z.ZodString>;
+    /**
+     * Duration of the processed variant, when a byte-mutating stage changed it
+     * (i.e. trim). Absent when the variant's duration matches the original.
+     */
+    processedDurationMs: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Peaks for the processed variant, once the `waveform` stage completes.
+     * Same normalization and bounds as `embed.waveform` (0–100, max 1000), so
+     * a view can never carry a larger payload than the record allows.
+     */
+    waveformPeaks: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    /**
+     * When the current runner's exclusive claim on this post expires.
+     *
+     * Queue delivery is at-least-once, so the same job can arrive twice and
+     * run CONCURRENTLY. `process()` is idempotent under sequential retry — it
+     * acts on `pending` and re-does nothing already settled — but two passes
+     * interleaved is a different failure: both read the same `pending` state,
+     * both bill the provider for the same stage, and both write
+     * `processedBlobCid`, so the surviving variant is whichever finished last
+     * and the other's blob is orphaned.
+     *
+     * A runner claims this field transactionally before doing any work and
+     * clears it when finished; a second runner finding it unexpired declines
+     * and returns. It is an EXPIRY, not a boolean lock, because the holder can
+     * die mid-run (instance recycled, process killed) with no chance to
+     * release — a plain flag would strand the post permanently, where a lapsed
+     * lease lets the next delivery pick it up.
+     *
+     * Internal, like the variant fields above: `toProcessingView` projects
+     * stages only, so this never reaches a client.
+     */
+    leaseUntil: z.ZodOptional<z.ZodEffects<z.ZodUnion<[z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodString, z.ZodNumber, z.ZodDate]>, Date, unknown>>;
+    updatedAt: z.ZodEffects<z.ZodUnion<[z.ZodType<unknown, z.ZodTypeDef, unknown>, z.ZodString, z.ZodNumber, z.ZodDate]>, Date, unknown>;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: Date;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    reprocess?: boolean | undefined;
+    processedBlobCid?: string | undefined;
+    processedMimeType?: string | undefined;
+    processedDurationMs?: number | undefined;
+    waveformPeaks?: number[] | undefined;
+    leaseUntil?: Date | undefined;
+}, {
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    reprocess?: boolean | undefined;
+    processedBlobCid?: string | undefined;
+    processedMimeType?: string | undefined;
+    processedDurationMs?: number | undefined;
+    waveformPeaks?: number[] | undefined;
+    leaseUntil?: unknown;
+    updatedAt?: unknown;
+}>;
+type ProcessingState = z.infer<typeof ProcessingStateSchema>;
+/**
+ * The processing status surfaced on the hydrated view — the per-stage status
+ * only (no internal storage fields: variant CID, duration, peaks, timestamps).
+ * Absent when no processing was requested.
+ */
+declare const ProcessingViewSchema: z.ZodObject<{
+    transcribe: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    denoise: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    trim: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+    waveform: z.ZodOptional<z.ZodEnum<["pending", "ready", "failed", "skipped"]>>;
+}, "strip", z.ZodTypeAny, {
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+}, {
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+}>;
+type ProcessingView = z.infer<typeof ProcessingViewSchema>;
+/**
+ * Project the stored state onto the view — drops every internal field.
+ *
+ * Derived from `PROCESSING_STAGES` rather than listing the stages by hand, so
+ * a stage added to the set cannot be silently omitted from the view (which
+ * would leave clients unable to tell "not requested" from "in progress").
+ */
+declare function toProcessingView(state: ProcessingState): ProcessingView;
+/** The record's own audio fields — canonical, inside the CID, never rewritten. */
+interface CanonicalAudioFields {
+    blobCid: string;
+    durationMs?: number;
+    waveform?: number[];
+}
+/**
+ * Resolve the audio fields a reader should see: canonical from the record,
+ * variant from `ProcessingState` wherever processing has superseded it.
+ *
+ * The three fields have to move together. Peaks are rendered ACROSS a duration
+ * and a duration describes a specific set of bytes, so serving a processed URL
+ * beside the original duration puts a scrubber out of alignment with the audio
+ * under it — the failure this function exists to prevent.
+ *
+ * Resolution is not a uniform `??` per field, because the state's fields do not
+ * all mean the same thing when absent:
+ *
+ *  - `processedDurationMs` absent is DEFINED as "the variant's duration equals
+ *    the original" (denoise transcodes without retiming), so falling back to
+ *    the record there is correct, not a guess.
+ *  - `waveformPeaks` carries no such guarantee. Recompute marks the stage
+ *    `pending` without clearing the field, so between a variant change and the
+ *    recomputed peaks landing it holds peaks for the SUPERSEDED variant. Hence
+ *    the status gate rather than a presence check.
+ *
+ * Peaks do not key off `processedBlobCid`: `waveform` always runs over the
+ * final variant, so when it is `ready` its peaks describe whatever playback
+ * resolves to here, variant or original alike.
+ */
+declare function resolveAudioVariant(canonical: CanonicalAudioFields, state: ProcessingState | undefined): CanonicalAudioFields;
+
+export { BYTE_MUTATING_STAGES, type CanonicalAudioFields, DERIVED_STAGES, PROCESSING_STAGES, type ProcessingRequest, ProcessingRequestSchema, type ProcessingStage, type ProcessingStageMap, ProcessingStageMapSchema, ProcessingStageSchema, type ProcessingStageStatus, ProcessingStageStatusSchema, type ProcessingState, ProcessingStateSchema, type ProcessingView, ProcessingViewSchema, type ResolvedProcessing, ResolvedProcessingSchema, resolveAudioVariant, toProcessingView };

package/dist/esm/index.js

@@ -1,12 +1,10 @@
 export { isFirestoreTimestamp } from './chunk-24KIXQZK.js';
-export { CreateAudioPostRequestSchema, UpdateProfileRequestSchema } from './chunk-FDM5FDN4.js';
-export { COLLECTIONS, EMBED_NSID, NSID, nsidForCollection } from './chunk-6LROFBKK.js';
+export { CreateAudioPostRequestSchema, PatchAudioPostRequestSchema } from './chunk-F5ZKFJL2.js';
+export { COLLECTIONS, EMBED_NSID, NSID } from './chunk-SBYNIQRZ.js';
 export { ConflictError, ForbiddenError, NotFoundError, RateLimitError, ServiceError, UnauthorizedError, ValidationError } from './chunk-7LW2FHLD.js';
 import './chunk-72G3LBUQ.js';
 export { buildReportedErrorEvent, reportError } from './chunk-BNNLHRH7.js';
-export { ActorViewSchema, PublicProfileDtoSchema } from './chunk-Y6HNNRVD.js';
-export { ActorProfileRecordSchema, AudioEmbedSchema, AudioEmbedViewSchema, AudioPostRecordSchema, AudioPostViewSchema, PostRecordPublicSchema, ReplyRefSchema, StrongRefSchema, TimedTranscriptSchema, TranscriptEnrichmentRecordSchema, TranscriptSegmentSchema, ViewerStateSchema } from './chunk-F7IHVM34.js';
-export { BlobRefSchema, resolveAudioUrl } from './chunk-5EHV73BA.js';
-export { ProfileViewAdminSchema, ProfileViewBasicSchema, ProfileViewDetailedSchema, ProfileViewSchema, ProfileViewSelfSchema, toProfileViewBasic } from './chunk-R6SBR3IG.js';
-export { FirestoreTimestampSchema, UserRecordSchema, httpsUrl } from './chunk-IHIBHQBJ.js';
+export { ActorProfileRecordSchema, AudioEmbedSchema, AudioEmbedViewSchema, AudioPostRecordSchema, AudioPostViewSchema, BYTE_MUTATING_STAGES, DERIVED_STAGES, PROCESSING_STAGES, PostRecordPublicSchema, ProcessingRequestSchema, ProcessingStageMapSchema, ProcessingStageSchema, ProcessingStageStatusSchema, ProcessingStateSchema, ProcessingViewSchema, ReplyRefSchema, ResolvedProcessingSchema, StrongRefSchema, TimedTranscriptSchema, TranscriptEnrichmentRecordSchema, TranscriptSegmentSchema, ViewerStateSchema, resolveAudioVariant, toProcessingView } from './chunk-TVOXIQKF.js';
+export { FirestoreTimestampSchema } from './chunk-D655OH2I.js';
+export { BlobRefSchema } from './chunk-SMK4OZNU.js';
 import './chunk-5JBD5THX.js';

package/dist/esm/nsid.d.ts

@@ -13,6 +13,8 @@ declare const NSID: {
     readonly ActorProfile: "dev.antiphony.actor.profile";
 };
 type NsidValue = typeof NSID[keyof typeof NSID];
+/** The subset of record NSIDs the core actually stores. */
+type StoredNsidValue = typeof NSID.AudioPost | typeof NSID.AudioTranscript;
 /**
  * Antiphony embed NSIDs. Embeds live inline on a post's `embed` field, not in
  * their own collection — kept out of `NSID`/`COLLECTIONS`.
@@ -22,13 +24,10 @@ declare const EMBED_NSID: {
     readonly RecordWithAudio: "dev.antiphony.embed.recordWithAudio";
 };
 /**
- * Maps AT Protocol record-type NSIDs to Firestore collection names.
- * When migrating to a PDS, this mapping becomes the adapter layer.
+ * Maps the STORED AT Protocol record-type NSIDs to Firestore collection
+ * names. When migrating to a PDS, this mapping becomes the adapter layer.
+ * `actor.profile` is deliberately absent — portable schema, no core storage.
  */
-declare const COLLECTIONS: Record<NsidValue, string>;
-/**
- * Reverse lookup: get the NSID for a Firestore collection name.
- */
-declare function nsidForCollection(collection: string): NsidValue | undefined;
+declare const COLLECTIONS: Record<StoredNsidValue, string>;
 
-export { COLLECTIONS, EMBED_NSID, NSID, type NsidValue, nsidForCollection };
+export { COLLECTIONS, EMBED_NSID, NSID, type NsidValue, type StoredNsidValue };