@antiphony/shared 0.5.0 → 0.6.0

package/dist/esm/types/audio.js

@@ -1,4 +1,6 @@
-export { ActorProfileRecordSchema, AudioEmbedSchema, AudioEmbedViewSchema, AudioPostRecordSchema, AudioPostViewSchema, PostRecordPublicSchema, ReplyRefSchema, StrongRefSchema, TimedTranscriptSchema, TranscriptEnrichmentRecordSchema, TranscriptSegmentSchema, ViewerStateSchema } from '../chunk-TVOXIQKF.js';
-import '../chunk-D655OH2I.js';
+export { ActorProfileRecordSchema, AudioEmbedSchema, AudioEmbedViewSchema, AudioPostRecordSchema, AudioPostViewSchema, PostRecordPublicSchema, ReplyRefSchema, StrongRefSchema, TimedTranscriptSchema, TranscriptEnrichmentRecordSchema, TranscriptSegmentSchema, ViewerStateSchema } from '../chunk-QQ5GOLYW.js';
 import '../chunk-SMK4OZNU.js';
+import '../chunk-AKIWUNNK.js';
+import '../chunk-D655OH2I.js';
+import '../chunk-KMQWUFMV.js';
 import '../chunk-5JBD5THX.js';

package/dist/esm/types/processing.d.ts

@@ -0,0 +1,336 @@
+import { z } from '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, {
+    waveform?: boolean | undefined;
+    transcribe?: boolean | undefined;
+    denoise?: boolean | undefined;
+    trim?: boolean | undefined;
+    reprocess?: boolean | undefined;
+}, {
+    waveform?: boolean | undefined;
+    transcribe?: boolean | undefined;
+    denoise?: boolean | undefined;
+    trim?: 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, {
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+}, {
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "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, {
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    reprocess?: boolean | undefined;
+}, {
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "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)
+ *
+ * `denoiseModel` is the exception: it has no canonical counterpart at all. It
+ * is provenance for the variant, recorded here because the variant is a blob
+ * CID rather than a record that could carry its own.
+ */
+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>;
+    /**
+     * Which denoiser produced the variant's denoise contribution — provenance,
+     * the counterpart to a transcript record's `model`.
+     *
+     * Lives here because a cleaned variant, unlike a transcript, has no record
+     * of its own to carry it: it is a blob CID on this state. Without it,
+     * changing denoisers leaves no way to tell which variants predate the
+     * switch, so nothing can identify what to re-run.
+     *
+     * Named for the STAGE, not the variant (`processedModel`), because it
+     * describes one link of the byte-mutating chain rather than the composed
+     * artifact. Trim contributes to the same variant and has no model, and a
+     * later external link would want its own field rather than to overwrite
+     * this one.
+     *
+     * Written on every successful denoise, never cleared — it moves with
+     * `processedBlobCid`, which is only ever set, never reset. A denoise that
+     * FAILS leaves both alone, which is correct: the variant still holds the
+     * previous denoiser's output, so the previous model still describes it.
+     *
+     * Internal, like the other variant fields — `toProcessingView` projects
+     * stages only, so this never reaches a client.
+     */
+    denoiseModel: z.ZodOptional<z.ZodString>;
+    /**
+     * 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;
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    reprocess?: boolean | undefined;
+    processedBlobCid?: string | undefined;
+    processedMimeType?: string | undefined;
+    processedDurationMs?: number | undefined;
+    denoiseModel?: string | undefined;
+    waveformPeaks?: number[] | undefined;
+    leaseUntil?: Date | undefined;
+}, {
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    reprocess?: boolean | undefined;
+    processedBlobCid?: string | undefined;
+    processedMimeType?: string | undefined;
+    processedDurationMs?: number | undefined;
+    denoiseModel?: string | 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, {
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "pending" | "ready" | "failed" | "skipped" | undefined;
+}, {
+    waveform?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    transcribe?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    denoise?: "pending" | "ready" | "failed" | "skipped" | undefined;
+    trim?: "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/types/processing.js

@@ -0,0 +1,3 @@
+export { BYTE_MUTATING_STAGES, DERIVED_STAGES, PROCESSING_STAGES, ProcessingRequestSchema, ProcessingStageMapSchema, ProcessingStageSchema, ProcessingStageStatusSchema, ProcessingStateSchema, ProcessingViewSchema, ResolvedProcessingSchema, resolveAudioVariant, toProcessingView } from '../chunk-AKIWUNNK.js';
+import '../chunk-D655OH2I.js';
+import '../chunk-5JBD5THX.js';

package/dist/esm/types/url.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+
+/**
+ * Scheme-restricted URL schema: an absolute `http:`/`https:` URL, trimmed.
+ *
+ * ## Why this exists
+ *
+ * `z.string().url()` is `new URL()` under the hood, and `new URL()` accepts
+ * ANY scheme. All of these parse clean through a bare `.url()`:
+ *
+ *     javascript:alert(1)
+ *     data:text/html,<script>alert(1)</script>
+ *     file:///etc/passwd
+ *     vbscript:msgbox(1)
+ *     blob:https://evil.example/x
+ *
+ * That is harmless for a value nobody dereferences and dangerous for one that
+ * clients do. `AudioEmbedView.url` is the field a player puts in `<audio src>`;
+ * `ActorProfileRecord.rssFeed` is the field an app renders as `<a href>`. A URL
+ * that reaches either of those unchecked is a stored-XSS shape — written once,
+ * fired for every viewer afterwards.
+ *
+ * So every URL field in this contract goes through this helper, and none of
+ * them uses a bare `.url()`. The `antiphony/no-bare-zod-url` ESLint rule
+ * enforces that, because "remember to use the helper" is not a control.
+ *
+ * ## Why `http:` is allowed, despite the name
+ *
+ * The name says https because https is what a deployment should serve; the rule
+ * admits `http:` because a self-hosted or local Antiphony is reached at
+ * `http://localhost:8787`, and `AudioEmbedView.url` is built from exactly that
+ * base (`ANTIPHONY_PUBLIC_BASE_URL`). Excluding plain http would make the
+ * contract unparseable in development for no safety gained: what this closes is
+ * scheme confusion, not transport confidentiality. Transport is a deployment
+ * concern, and the deployment that matters is https already.
+ *
+ * ## Why a string check and not a `.refine()`
+ *
+ * Two reasons, both practical:
+ *
+ *  - **It stays a `ZodString`.** A `.refine()` wraps the schema in `ZodEffects`,
+ *    which costs consumers `.extend()`-friendliness and makes the OpenAPI
+ *    generator emit a weaker schema. As a plain string check the constraint
+ *    survives into `openapi.json` as a `pattern`, so a consumer in another
+ *    language reads the rule instead of having to already know it.
+ *  - **It is checked against the raw string, not a parsed `protocol`.** HTML
+ *    strips tabs and newlines out of URL attributes before dereferencing them,
+ *    so a scheme split by a tab is a live `javascript:` URL in a browser — and
+ *    one `new URL()` parses happily. Requiring the string to LITERALLY begin
+ *    `http://` or `https://` rejects that whole family without enumerating it.
+ *
+ * `.trim()` runs first so surrounding whitespace is normalised away rather than
+ * sneaking a scheme past the anchor. It is a normalisation, not a loosening:
+ * bare `.url()` accepted padded input too, it just kept the padding.
+ *
+ * One fidelity note on that generated `pattern`: JSON Schema has no way to
+ * express a case-insensitive regex, so `openapi.json` documents
+ * `^https?:\/\/` without the `i` flag. `HTTPS://x` therefore passes here and
+ * fails a strict reading of the document. Real URLs carry a lowercase scheme,
+ * and the alternative — dropping `i` — would reject input for cosmetics, so the
+ * runtime stays the more permissive of the two on that one axis.
+ *
+ * Usage:
+ *
+ *     url:     httpsUrl()
+ *     rssFeed: httpsUrl().optional()
+ */
+declare function httpsUrl(): z.ZodString;
+
+export { httpsUrl };

package/dist/esm/types/url.js

@@ -0,0 +1,2 @@
+export { httpsUrl } from '../chunk-KMQWUFMV.js';
+import '../chunk-5JBD5THX.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antiphony/shared",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared types, Zod schemas, and codecs for Antiphony — open audio call-and-response infrastructure and AT Protocol lexicons.",
   "license": "MIT",
   "homepage": "https://docs.antiphony.dev",
@@ -137,14 +137,16 @@
     "lint": "eslint . --max-warnings=0",
     "test": "vitest run"
   },
-  "dependencies": {
+  "//peerDependencies": "zod is a PEER, not a dependency, and the build has always assumed as much: tsup.config.ts marks it `external` so that there is ONE zod module instance shared with the consumer — the comment there spells out the consequence, that `@hono/zod-openapi`'s `.openapi()` extension never reaches schemas defined here if the instance is duplicated. Declaring it under `dependencies` said the opposite, that this package brings its own, and the contradiction was not theoretical: a consumer pinned to zod 3.22.4 against this package's `^3.24.1` gets TWO instances, 3.22.4 hoisted and 3.25.76 nested here. That is a live hazard inside zod 3, not a hedge against zod 4. As a peer, npm resolves one instance and says so when it cannot. The range is `^3.24.1` and is deliberately NOT widened to include `^4.0.0`: the schemas here are written against the zod 3 API, #148 verified that a zod 4 consumer breaks at parse time, and a peer range that overstates what the code supports is exactly the failure mode `@hono/zod-openapi` demonstrated with its `zod: >=3.0.0` — a range npm cannot fault, since 3.25.76 satisfies it, while the code underneath needed `^3.20.2`. Widen it only when the schemas actually move. ⚠️ SHIPS IN 0.6.0, which is unreleased — this changes the install contract, so a consumer that did not declare zod itself must now do so (npm 7+ auto-installs peers, but a consumer with `legacy-peer-deps` set does not). Vox Pop already declares zod in every workspace, so it is a no-op there.",
+  "peerDependencies": {
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "tsup": "^8.5.1",
-    "typescript-eslint": "^8.18.0",
+    "typescript-eslint": "^8.70.0",
     "typescript": "^5.7.2",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "zod": "^3.24.1"
   }
 }