@voyantjs/extras 0.19.0 → 0.20.0

package/dist/catalog-policy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Catalog plane field policy for `packages/extras`.
+ *
+ * Extras are booking add-ons (optional line items layered on a booked
+ * parent product) — **not independently sellable inventory**. Per
+ * architecture §3.3.1, extras are a partial-adoption vertical:
+ *
+ *   - **Adopt:** provenance shape (§5.1), booking snapshot graph (§5.3),
+ *     catalog event taxonomy for the cancellation/fulfillment lifecycle.
+ *   - **Skip:** search index projection (§5.4), editorial overlay store
+ *     (§5.2), embeddings / RAG (Phase 2). Extras are discovered through
+ *     the parent's surface, not via standalone catalog browse.
+ *
+ * Every field below has `reindex: "none"` because extras don't appear in
+ * the search index. Snapshot mode is `"on-book"` (or `"never"` for
+ * volatile fields) because refunds and audits need to know exactly what
+ * extra a customer added.
+ *
+ * Scope of this file:
+ *   - The `product_extras` table (extra catalog definitions).
+ *
+ * Out of scope:
+ *   - `option_extra_configs` — option-level overrides; promoted child.
+ *   - `booking_extras` — runtime line items on a booking; not catalog data.
+ */
+import { type FieldPolicyInput } from "@voyantjs/catalog/contract";
+declare const EXTRAS_FIELD_POLICY: FieldPolicyInput[];
+export declare const extrasCatalogPolicy: import("@voyantjs/catalog").FieldPolicy[];
+export { EXTRAS_FIELD_POLICY };
+//# sourceMappingURL=catalog-policy.d.ts.map

package/dist/catalog-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-policy.d.ts","sourceRoot":"","sources":["../src/catalog-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAErF,QAAA,MAAM,mBAAmB,EAAE,gBAAgB,EA0Q1C,CAAA;AAED,eAAO,MAAM,mBAAmB,2CAAyC,CAAA;AAEzE,OAAO,EAAE,mBAAmB,EAAE,CAAA"}

package/dist/catalog-policy.js

@@ -0,0 +1,291 @@
+/**
+ * Catalog plane field policy for `packages/extras`.
+ *
+ * Extras are booking add-ons (optional line items layered on a booked
+ * parent product) — **not independently sellable inventory**. Per
+ * architecture §3.3.1, extras are a partial-adoption vertical:
+ *
+ *   - **Adopt:** provenance shape (§5.1), booking snapshot graph (§5.3),
+ *     catalog event taxonomy for the cancellation/fulfillment lifecycle.
+ *   - **Skip:** search index projection (§5.4), editorial overlay store
+ *     (§5.2), embeddings / RAG (Phase 2). Extras are discovered through
+ *     the parent's surface, not via standalone catalog browse.
+ *
+ * Every field below has `reindex: "none"` because extras don't appear in
+ * the search index. Snapshot mode is `"on-book"` (or `"never"` for
+ * volatile fields) because refunds and audits need to know exactly what
+ * extra a customer added.
+ *
+ * Scope of this file:
+ *   - The `product_extras` table (extra catalog definitions).
+ *
+ * Out of scope:
+ *   - `option_extra_configs` — option-level overrides; promoted child.
+ *   - `booking_extras` — runtime line items on a booking; not catalog data.
+ */
+import { defineFieldPolicy } from "@voyantjs/catalog/contract";
+const EXTRAS_FIELD_POLICY = [
+    // ── Source pointer / provenance ─────────────────────────────────────────
+    {
+        path: "source.kind",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "source.ref",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "seller.operator_id",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "static",
+    },
+    // ── Identity / lifecycle ────────────────────────────────────────────────
+    {
+        path: "id",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "first-class-table",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "static",
+    },
+    {
+        path: "code",
+        class: "managed",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "createdAt",
+        class: "managed",
+        merge: "source-only",
+        drift: "none",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "static",
+    },
+    {
+        path: "updatedAt",
+        class: "managed",
+        merge: "source-only",
+        drift: "none",
+        reindex: "none",
+        snapshot: "never",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Cross-module reference (the parent product the extra attaches to) ──
+    {
+        path: "productId",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Snapshot-relevant managed fields ────────────────────────────────────
+    // Extras' name/description aren't merchandised standalone — they're
+    // shown inside the parent product's add-on UI. Marked as managed for
+    // simplicity; if a future case requires marketing overrides on extras'
+    // names, this can be promoted to merchandisable.
+    {
+        path: "name",
+        class: "managed",
+        merge: "source-only",
+        drift: "medium",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "description",
+        class: "managed",
+        merge: "source-only",
+        drift: "low",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "blob-only",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Selection / pricing structure (snapshotted at book time) ───────────
+    {
+        path: "selectionType",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "pricingMode",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-quote-and-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "pricedPerPerson",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-quote-and-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "minQuantity",
+        class: "structural",
+        merge: "source-only",
+        drift: "medium",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "maxQuantity",
+        class: "structural",
+        merge: "source-only",
+        drift: "medium",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "defaultQuantity",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "active",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "sortOrder",
+        class: "structural",
+        merge: "source-only",
+        drift: "none",
+        reindex: "none",
+        snapshot: "never",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "ops",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+];
+export const extrasCatalogPolicy = defineFieldPolicy(EXTRAS_FIELD_POLICY);
+export { EXTRAS_FIELD_POLICY };

package/dist/routes.d.ts

@@ -44,24 +44,24 @@ export declare const extrasRoutes: import("hono/hono-base").HonoBase<Env, {
             input: {};
             output: {
                 data: {
-                    metadata: {
-                        [x: string]: import("hono/utils/types").JSONValue;
-                    } | null;
                     id: string;
-                    name: string;
+                    code: string | null;
                     createdAt: string;
                     updatedAt: string;
-                    description: string | null;
-                    code: string | null;
-                    active: boolean;
                     productId: string;
+                    name: string;
+                    description: string | null;
                     selectionType: "optional" | "required" | "default_selected" | "unavailable";
                     pricingMode: "included" | "per_person" | "per_booking" | "quantity_based" | "on_request" | "free";
                     pricedPerPerson: boolean;
                     minQuantity: number | null;
                     maxQuantity: number | null;
                     defaultQuantity: number | null;
+                    active: boolean;
                     sortOrder: number;
+                    metadata: {
+                        [x: string]: import("hono/utils/types").JSONValue;
+                    } | null;
                 } | null;
             };
             outputFormat: "json";
@@ -223,21 +223,21 @@ export declare const extrasRoutes: import("hono/hono-base").HonoBase<Env, {
             input: {};
             output: {
                 data: {
-                    metadata: {
-                        [x: string]: import("hono/utils/types").JSONValue;
-                    } | null;
                     id: string;
                     createdAt: string;
                     updatedAt: string;
-                    notes: string | null;
-                    active: boolean;
                     selectionType: "optional" | "required" | "default_selected" | "unavailable" | null;
                     pricingMode: "included" | "per_person" | "per_booking" | "quantity_based" | "on_request" | "free" | null;
                     pricedPerPerson: boolean | null;
                     minQuantity: number | null;
                     maxQuantity: number | null;
                     defaultQuantity: number | null;
+                    active: boolean;
                     sortOrder: number;
+                    metadata: {
+                        [x: string]: import("hono/utils/types").JSONValue;
+                    } | null;
+                    notes: string | null;
                     optionId: string;
                     productExtraId: string;
                     isDefault: boolean;
@@ -406,19 +406,19 @@ export declare const extrasRoutes: import("hono/hono-base").HonoBase<Env, {
             input: {};
             output: {
                 data: {
-                    metadata: {
-                        [x: string]: import("hono/utils/types").JSONValue;
-                    } | null;
                     id: string;
-                    name: string;
                     createdAt: string;
                     updatedAt: string;
-                    status: "draft" | "selected" | "confirmed" | "cancelled" | "fulfilled";
-                    notes: string | null;
+                    name: string;
                     description: string | null;
-                    bookingId: string;
                     pricingMode: "included" | "per_person" | "per_booking" | "quantity_based" | "on_request" | "free";
                     pricedPerPerson: boolean;
+                    metadata: {
+                        [x: string]: import("hono/utils/types").JSONValue;
+                    } | null;
+                    status: "draft" | "selected" | "confirmed" | "cancelled" | "fulfilled";
+                    notes: string | null;
+                    bookingId: string;
                     productExtraId: string | null;
                     optionExtraConfigId: string | null;
                     quantity: number;

package/dist/service-catalog-plane.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Catalog-plane integration for the extras service.
+ *
+ * Extras are a **partial-adoption vertical** per architecture §3.3.1: they
+ * participate in provenance + booking snapshot + catalog event taxonomy,
+ * but skip the search index and overlay store. The service-plane integration
+ * here reflects that — `getResolvedExtraById` returns a resolved view but
+ * the resolver always sees an empty overlay set (extras have no overlay
+ * rows; the catalog-policy file declares no merchandisable fields).
+ *
+ * The value of running through the catalog-plane resolver anyway is
+ * uniformity: extras' projection and visibility filtering use the same
+ * machinery as every other vertical, and snapshot capture at booking commit
+ * (the most important participation surface for extras) reuses
+ * `productExtraRowToProjection` to build the frozen payload.
+ *
+ * See `docs/architecture/catalog-architecture.md` §9.1 + §3.3.1.
+ */
+import { type CaptureSnapshotInput, type DocumentBuilder, type DocumentEmitter, type IndexerDocument, type IndexerSlice, type PricingBasis, type Provenance, type ResolvedView, type ResolverScope } from "@voyantjs/catalog";
+import type { AnyDrizzleDb } from "@voyantjs/db";
+import { productExtras } from "./schema.js";
+/**
+ * Maps a product-extra row to a field-keyed projection. Extras almost
+ * always inherit their provenance from the parent product they attach to;
+ * the caller passes the parent's source kind / ref through, defaulting to
+ * `owned` for operator-defined extras.
+ */
+export declare function productExtraRowToProjection(row: typeof productExtras.$inferSelect, context: {
+    sellerOperatorId: string;
+    sourceKind?: string;
+    sourceRef?: string;
+}): ReadonlyMap<string, unknown>;
+export declare function productExtraProvenance(_row: typeof productExtras.$inferSelect, context: {
+    sellerOperatorId: string;
+    sourceKind?: string;
+    sourceRef?: string;
+}): Provenance;
+export interface ProductExtraCatalogContext {
+    sellerOperatorId: string;
+    scope: ResolverScope;
+    sourceKind?: string;
+    sourceRef?: string;
+}
+/**
+ * Catalog-aware extra fetch. The catalog-policy declares no merchandisable
+ * fields for extras (per §3.3.1 partial adoption), so the resolver acts as
+ * a pure visibility filter rather than an overlay-merge engine. Useful
+ * primarily for snapshot capture at booking time.
+ */
+export declare function getResolvedExtraById(db: AnyDrizzleDb, id: string, context: ProductExtraCatalogContext): Promise<ResolvedView | null>;
+export declare function listResolvedExtras(db: AnyDrizzleDb, rows: ReadonlyArray<typeof productExtras.$inferSelect>, context: ProductExtraCatalogContext): Promise<ResolvedView[]>;
+/**
+ * Build a `CaptureSnapshotInput` for a product extra. Extras participate
+ * in the snapshot graph (per §3.3.1 partial adoption) so refunds can know
+ * exactly what add-on the customer purchased and what selectionType /
+ * pricingMode applied at booking time.
+ */
+export declare function buildExtraSnapshotInput(db: AnyDrizzleDb, extraId: string, context: ProductExtraCatalogContext & {
+    pricingBasis?: PricingBasis;
+}): Promise<Omit<CaptureSnapshotInput, "bookingId"> | null>;
+/**
+ * Note: per architecture §3.3.1, extras opt out of search-index
+ * participation — the catalog-policy declares every field with
+ * `reindex: "none"`. The emitter is provided for completeness (a deployment
+ * may opt extras into the index for ops-side keyword search) but production
+ * deployments should not register an extras emitter with the IndexerService.
+ */
+export declare function createExtraDocumentEmitter(context: {
+    sellerOperatorId: string;
+    sourceKind?: string;
+    sourceRef?: string;
+}): DocumentEmitter<typeof productExtras.$inferSelect>;
+export declare function createExtraDocumentBuilder(db: AnyDrizzleDb, context: {
+    sellerOperatorId: string;
+    sourceKind?: string;
+    sourceRef?: string;
+}): DocumentBuilder;
+export type { CaptureSnapshotInput, DocumentBuilder, DocumentEmitter, IndexerDocument, IndexerSlice, PricingBasis, Provenance, ResolvedView, ResolverScope, };
+//# sourceMappingURL=service-catalog-plane.d.ts.map

package/dist/service-catalog-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-catalog-plane.d.ts","sourceRoot":"","sources":["../src/service-catalog-plane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,eAAe,EACpB,KAAK,eAAe,EAEpB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,EAEnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAIhD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAU3C;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,aAAa,CAAC,YAAY,EACtC,OAAO,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CA4B9B;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,aAAa,CAAC,YAAY,EACvC,OAAO,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,UAAU,CAMZ;AAED,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,MAAM,CAAA;IACxB,KAAK,EAAE,aAAa,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAW9B;AAED,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,aAAa,CAAC,OAAO,aAAa,CAAC,YAAY,CAAC,EACtD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,YAAY,EAAE,CAAC,CAazB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,0BAA0B,GAAG;IAAE,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC,CAUzD;AAMD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,eAAe,CAAC,OAAO,aAAa,CAAC,YAAY,CAAC,CAarD;AAED,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E,eAAe,CAYjB;AAED,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,aAAa,GACd,CAAA"}

package/dist/service-catalog-plane.js

@@ -0,0 +1,156 @@
+/**
+ * Catalog-plane integration for the extras service.
+ *
+ * Extras are a **partial-adoption vertical** per architecture §3.3.1: they
+ * participate in provenance + booking snapshot + catalog event taxonomy,
+ * but skip the search index and overlay store. The service-plane integration
+ * here reflects that — `getResolvedExtraById` returns a resolved view but
+ * the resolver always sees an empty overlay set (extras have no overlay
+ * rows; the catalog-policy file declares no merchandisable fields).
+ *
+ * The value of running through the catalog-plane resolver anyway is
+ * uniformity: extras' projection and visibility filtering use the same
+ * machinery as every other vertical, and snapshot capture at booking commit
+ * (the most important participation surface for extras) reuses
+ * `productExtraRowToProjection` to build the frozen payload.
+ *
+ * See `docs/architecture/catalog-architecture.md` §9.1 + §3.3.1.
+ */
+import { buildIndexerDocument, buildSnapshotInputFromView, createFieldPolicyRegistry, resolveEntityView, } from "@voyantjs/catalog";
+import { eq } from "drizzle-orm";
+import { extrasCatalogPolicy } from "./catalog-policy.js";
+import { productExtras } from "./schema.js";
+let _registry;
+function getExtrasRegistry() {
+    if (!_registry) {
+        _registry = createFieldPolicyRegistry(extrasCatalogPolicy);
+    }
+    return _registry;
+}
+/**
+ * Maps a product-extra row to a field-keyed projection. Extras almost
+ * always inherit their provenance from the parent product they attach to;
+ * the caller passes the parent's source kind / ref through, defaulting to
+ * `owned` for operator-defined extras.
+ */
+export function productExtraRowToProjection(row, context) {
+    return new Map([
+        // Provenance
+        ["source.kind", context.sourceKind ?? "owned"],
+        ["source.ref", context.sourceRef],
+        ["seller.operator_id", context.sellerOperatorId],
+        // Identity + cross-module reference
+        ["id", row.id],
+        ["code", row.code],
+        ["productId", row.productId],
+        ["createdAt", row.createdAt],
+        ["updatedAt", row.updatedAt],
+        // Snapshot-relevant managed fields
+        ["name", row.name],
+        ["description", row.description],
+        // Selection / pricing structure
+        ["selectionType", row.selectionType],
+        ["pricingMode", row.pricingMode],
+        ["pricedPerPerson", row.pricedPerPerson],
+        ["minQuantity", row.minQuantity],
+        ["maxQuantity", row.maxQuantity],
+        ["defaultQuantity", row.defaultQuantity],
+        ["active", row.active],
+        ["sortOrder", row.sortOrder],
+    ]);
+}
+export function productExtraProvenance(_row, context) {
+    return {
+        source_kind: context.sourceKind ?? "owned",
+        source_freshness: context.sourceKind && context.sourceKind !== "owned" ? "sync" : "static",
+        source_ref: context.sourceRef,
+    };
+}
+/**
+ * Catalog-aware extra fetch. The catalog-policy declares no merchandisable
+ * fields for extras (per §3.3.1 partial adoption), so the resolver acts as
+ * a pure visibility filter rather than an overlay-merge engine. Useful
+ * primarily for snapshot capture at booking time.
+ */
+export async function getResolvedExtraById(db, id, context) {
+    const rows = await db.select().from(productExtras).where(eq(productExtras.id, id)).limit(1);
+    const row = rows[0];
+    if (!row)
+        return null;
+    const projection = productExtraRowToProjection(row, {
+        sellerOperatorId: context.sellerOperatorId,
+        sourceKind: context.sourceKind,
+        sourceRef: context.sourceRef,
+    });
+    return resolveEntityView(db, getExtrasRegistry(), "extras", id, projection, context.scope);
+}
+export async function listResolvedExtras(db, rows, context) {
+    const registry = getExtrasRegistry();
+    const views = [];
+    for (const row of rows) {
+        const projection = productExtraRowToProjection(row, {
+            sellerOperatorId: context.sellerOperatorId,
+            sourceKind: context.sourceKind,
+            sourceRef: context.sourceRef,
+        });
+        const view = await resolveEntityView(db, registry, "extras", row.id, projection, context.scope);
+        views.push(view);
+    }
+    return views;
+}
+/**
+ * Build a `CaptureSnapshotInput` for a product extra. Extras participate
+ * in the snapshot graph (per §3.3.1 partial adoption) so refunds can know
+ * exactly what add-on the customer purchased and what selectionType /
+ * pricingMode applied at booking time.
+ */
+export async function buildExtraSnapshotInput(db, extraId, context) {
+    const view = await getResolvedExtraById(db, extraId, context);
+    if (!view)
+        return null;
+    return buildSnapshotInputFromView(view, {
+        entityModule: "extras",
+        entityId: extraId,
+        sourceKind: context.sourceKind ?? "owned",
+        sourceRef: context.sourceRef,
+        pricingBasis: context.pricingBasis,
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Indexer document emission
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Note: per architecture §3.3.1, extras opt out of search-index
+ * participation — the catalog-policy declares every field with
+ * `reindex: "none"`. The emitter is provided for completeness (a deployment
+ * may opt extras into the index for ops-side keyword search) but production
+ * deployments should not register an extras emitter with the IndexerService.
+ */
+export function createExtraDocumentEmitter(context) {
+    const registry = getExtrasRegistry();
+    return {
+        vertical: "extras",
+        emit(source, slice) {
+            const projection = productExtraRowToProjection(source, {
+                sellerOperatorId: context.sellerOperatorId,
+                sourceKind: context.sourceKind,
+                sourceRef: context.sourceRef,
+            });
+            return buildIndexerDocument(registry, projection, slice, source.id);
+        },
+    };
+}
+export function createExtraDocumentBuilder(db, context) {
+    const emitter = createExtraDocumentEmitter(context);
+    return async (entityId, slice) => {
+        const rows = await db
+            .select()
+            .from(productExtras)
+            .where(eq(productExtras.id, entityId))
+            .limit(1);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return emitter.emit(row, slice);
+    };
+}

package/dist/service.d.ts

@@ -53,22 +53,22 @@ export declare const extrasService: {
         updatedAt: Date;
     } | null>;
     createProductExtra(db: PostgresJsDatabase, data: CreateProductExtraInput): Promise<{
-        metadata: Record<string, unknown> | null;
         id: string;
-        name: string;
+        code: string | null;
         createdAt: Date;
         updatedAt: Date;
-        description: string | null;
-        code: string | null;
-        active: boolean;
         productId: string;
+        name: string;
+        description: string | null;
         selectionType: "optional" | "required" | "default_selected" | "unavailable";
         pricingMode: "included" | "per_person" | "per_booking" | "quantity_based" | "on_request" | "free";
         pricedPerPerson: boolean;
         minQuantity: number | null;
         maxQuantity: number | null;
         defaultQuantity: number | null;
+        active: boolean;
         sortOrder: number;
+        metadata: Record<string, unknown> | null;
     } | null>;
     updateProductExtra(db: PostgresJsDatabase, id: string, data: UpdateProductExtraInput): Promise<{
         id: string;
@@ -133,19 +133,19 @@ export declare const extrasService: {
         updatedAt: Date;
     } | null>;
     createOptionExtraConfig(db: PostgresJsDatabase, data: CreateOptionExtraConfigInput): Promise<{
-        metadata: Record<string, unknown> | null;
         id: string;
         createdAt: Date;
         updatedAt: Date;
-        notes: string | null;
-        active: boolean;
         selectionType: "optional" | "required" | "default_selected" | "unavailable" | null;
         pricingMode: "included" | "per_person" | "per_booking" | "quantity_based" | "on_request" | "free" | null;
         pricedPerPerson: boolean | null;
         minQuantity: number | null;
         maxQuantity: number | null;
         defaultQuantity: number | null;
+        active: boolean;
         sortOrder: number;
+        metadata: Record<string, unknown> | null;
+        notes: string | null;
         optionId: string;
         productExtraId: string;
         isDefault: boolean;
@@ -221,17 +221,17 @@ export declare const extrasService: {
         updatedAt: Date;
     } | null>;
     createBookingExtra(db: PostgresJsDatabase, data: CreateBookingExtraInput): Promise<{
-        metadata: Record<string, unknown> | null;
         id: string;
-        name: string;
         createdAt: Date;
         updatedAt: Date;
-        status: "draft" | "selected" | "confirmed" | "cancelled" | "fulfilled";
-        notes: string | null;
+        name: string;
         description: string | null;
-        bookingId: string;
         pricingMode: "included" | "per_person" | "per_booking" | "quantity_based" | "on_request" | "free";
         pricedPerPerson: boolean;
+        metadata: Record<string, unknown> | null;
+        status: "draft" | "selected" | "confirmed" | "cancelled" | "fulfilled";
+        notes: string | null;
+        bookingId: string;
         productExtraId: string | null;
         optionExtraConfigId: string | null;
         quantity: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/extras",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -29,14 +29,15 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyantjs/core": "0.19.0",
-    "@voyantjs/db": "0.19.0",
-    "@voyantjs/hono": "0.19.0"
+    "@voyantjs/core": "0.20.0",
+    "@voyantjs/db": "0.20.0",
+    "@voyantjs/hono": "0.20.0",
+    "@voyantjs/catalog": "0.20.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",
-    "@voyantjs/bookings": "0.19.0",
-    "@voyantjs/products": "0.19.0",
+    "@voyantjs/bookings": "0.20.0",
+    "@voyantjs/products": "0.20.0",
     "@voyantjs/voyant-typescript-config": "0.1.0"
   },
   "files": [