@wildo-ai/zod-decorators 1.1.2 → 1.1.3

package/dist/esm/zod-decorators.types.js

@@ -729,7 +729,14 @@ export const FileMimeTypeGroups = {
     ],
 };
 /**
- * File nature classification for constraint validation and UI display.
+ * @wildo_source:part:start zod.decorators.file-vocabularies facet:layer:shared facet:audience:app-developer
+ *
+ * The vocabularies a `z_file()` field selects from. Pick a member of each; the option bag names the
+ * type, and these are the values.
+ *
+ * File nature classification, chosen with `z_file({ nature })`. It selects which per-nature
+ * constraint bag applies and how the form control and display surface behave. `ALL` accepts any
+ * kind and is the right answer for a generic attachment field.
  */
 export var FileNature;
 (function (FileNature) {
@@ -741,6 +748,7 @@ export var FileNature;
     FileNature["ARCHIVE"] = "archive";
     FileNature["ALL"] = "all";
 })(FileNature || (FileNature = {}));
+/** @wildo_source:part:end zod.decorators.file-vocabularies */
 /**
  * Rendering-level file nature categories.
  *
@@ -835,7 +843,19 @@ export var FileActivationPolicy;
     FileActivationPolicy["CUSTOM"] = "custom";
 })(FileActivationPolicy || (FileActivationPolicy = {}));
 /**
- * Storage providers accepted for file uploads.
+ * @wildo_source:part:start zod.decorators.file-vocabularies
+ *
+ * Where a field's bytes may be stored, chosen with `z_file({ storageAccepted: [...] })`. ORDER
+ * EXPRESSES PREFERENCE: list several and the first CONFIGURED one is used. Omit the option entirely
+ * and the field resolves to managed storage.
+ *
+ * ⚠️ **Only `WILDO_MANAGED` and `LOCAL_DIRECTORY` have a provider behind them.** `ONEDRIVE`,
+ * `GOOGLE_DRIVE` and `DROPBOX` are declared vocabulary with no implementation — a field naming only
+ * those has no configured provider, and startup configuration validation refuses the application
+ * rather than letting it serve a field that could never accept an upload.
+ *
+ * ⚠️ **The target is decided once, when the file is created, and the object never moves.** Changing
+ * a field's declared target changes where NEW files go; it does not relocate what is already stored.
  */
 export var FileStorageAccepted;
 (function (FileStorageAccepted) {
@@ -884,6 +904,39 @@ export const AudioFormat = {
     OGG: 'ogg',
     AAC: 'aac',
 };
+/** @wildo_source:part:end zod.decorators.file-nature-constraints */
+/*
+ * MAINTAINER NOTE — deliberately OUTSIDE the `zod.decorators.rag-source` anchor below, because the
+ * anchor ships into every generated application and an application author needs the vocabulary, not
+ * its history. The one sentence they DO need ("there is no semantic member, and why") is inside.
+ *
+ * ## `SEMANTIC` was a fifth member here, and was REMOVED on 2026-09-09 (#434)
+ *
+ * It read `SEMANTIC — split at embedding-detected topic boundaries` and was never implemented: every
+ * field authoring it silently degraded to `FIXED_SIZE`. The obvious fix was to build it. The measured
+ * answer is that it is not worth building, so the member went instead — recorded because "add the
+ * missing one back" is what the next reader will otherwise propose.
+ *
+ * Chroma's chunking evaluation benchmarks exactly this algorithm. Its `KamradtSemanticChunker` scored
+ * 83.6% recall / 1.5% precision against `RecursiveCharacterTextSplitter`'s 89.5% / 3.6% — worse on
+ * BOTH axes than the `RECURSIVE` member beside it — and the report calls it "slightly below average
+ * across all metrics". A 2026 cost-versus-effectiveness study reached the same conclusion
+ * independently: expensive chunking methods "do not yield meaningful effectiveness improvements while
+ * introducing substantially higher computational overhead", with only fixed-size and recursive
+ * "robust across datasets".
+ * spec-cite: Chroma, "Evaluating Chunking Strategies for Retrieval"
+ * (https://www.trychroma.com/research/evaluating-chunking); arXiv:2606.00881. Both read 2026-09-09.
+ *
+ * The architectural cost was the other half, and it is Wildo-specific. Boundaries computed from
+ * embeddings make the CHUNKER a client of the embeddings provider on the resource WRITE path, and
+ * force the embedding model into `chunkingConfigHash` — after which a model migration RE-CHUNKS
+ * rather than re-embedding in place, discarding exactly the property the dimension-flexible vector
+ * column and the deferred `rag:embedding-drain` batch exist to provide.
+ *
+ * If retrieval quality is ever the MEASURED bottleneck, the evidence points at CONTEXTUAL RETRIEVAL
+ * (prepend document-level context to each chunk before embedding), not at topic boundaries. That
+ * changes what is embedded rather than when boundaries are computed, so it costs none of the above.
+ */
 /**
  * @wildo_source:part:start zod.decorators.rag-source facet:layer:shared facet:family:decorator facet:family:param-surface facet:kind:api facet:audience:app-developer
  *
@@ -902,7 +955,6 @@ export const AudioFormat = {
  *
  * - `FIXED_SIZE` — split every `chunkSize` characters/tokens regardless of structure.
  * - `RECURSIVE` — split on a separator hierarchy (paragraph → sentence → word) down to `chunkSize`.
- * - `SEMANTIC` — split at embedding-detected topic boundaries.
  * - `MARKDOWN` — split on markdown structure (headings, lists, code fences).
  * - `CODE` — split on source-code structure (functions, classes, blocks). Unified in (2026-08-26)
  *   from a second copy of this vocabulary that `saas-models` then carried: the member sets differed
@@ -910,11 +962,16 @@ export const AudioFormat = {
  *   invalidated configurations authored against the wider one — so the union won. That second copy,
  *   and the agent-level RAG configuration schemas around it, were retired on 2026-08-27 as a
  *   pre-capability design the shipped capability superseded; this object is now the only home.
+ *
+ * There is deliberately NO semantic/embedding-based member. It is the option people reach for
+ * first, and published evaluations put it BELOW `RECURSIVE` on both recall and precision while
+ * costing an embedding pass per document — so `RECURSIVE` is the right default for prose, and the
+ * two structure-aware members are for text whose structure carries meaning.
+ *
  */
 export const RAGChunkingStrategy = {
     FIXED_SIZE: 'fixed_size',
     RECURSIVE: 'recursive',
-    SEMANTIC: 'semantic',
     MARKDOWN: 'markdown',
     CODE: 'code',
 };
@@ -933,6 +990,15 @@ export var FileGenerationSource;
     FileGenerationSource["PDF_TEMPLATE"] = "pdfTemplate";
 })(FileGenerationSource || (FileGenerationSource = {}));
 /**
+ * @wildo_source:part:start zod.decorators.file-vocabularies
+ *
+ * What happens to the file when its parent record is deleted, chosen with
+ * `z_file({ onParentDelete })`. Defaults to `CASCADE`.
+ *
+ * ⚠️ `SOFT_DELETE` behaves IDENTICALLY to `CASCADE` at runtime today. It exists as an explicit
+ * semantic marker for consumers that want to model a softer intent — choosing it does not currently
+ * change what happens to the file.
+ *
  * File behavior when parent resource is deleted.
  * - CASCADE: Mark the file deleted as part of parent removal; physical storage cleanup is deferred to the cleanup batch
  * - SOFT_DELETE: Same current runtime behavior as CASCADE, but keeps an explicit semantic marker for consumers that want to model softer intent
@@ -1339,10 +1405,12 @@ export var ZodDecorator;
      * could ask to have erased.
      *
      * ⚠️ This is a WRITE-side claim — "when this field CHANGES, the change itself is evidence" — and
-     * is independent of the READ-side disclosure trail. The only disclosure trigger the framework has
-     * is `isBackendOnly({ isReturnedAtCreation: true })`, which fires one `FIELD_ACCESS` event when a
-     * server-minted secret is first exposed. A field can carry either, both, or neither. There is no
-     * general "audit every read of this field" marker — do not go looking for one.
+     * is independent of the READ-side disclosure trail. The framework has exactly two disclosure
+     * triggers: `isBackendOnly({ isReturnedAtCreation: true })`, which fires one `FIELD_ACCESS` event
+     * when a server-minted secret is first exposed on a create, and `.isEphemeral()`, which fires on
+     * any operation so a rotate or regenerate is recorded as well. A field can carry any combination
+     * of the three markers. There is still no general "audit every read of this field" marker; do not
+     * go looking for one.
      *
      * assurance-control: WILDO.SECRETS.DISCLOSURE_AUDIT
      */