@openlup/core 0.0.0 → 0.6.0

package/src/fulfillment/facts.ts

@@ -0,0 +1,300 @@
+import { z } from "zod";
+
+/** @beta */ export const NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION = 1 as const;
+/** @beta */ export const NORMALIZED_FULFILLMENT_FACT_PREVIOUS_SCHEMA_VERSION = 0 as const;
+/** @beta */ export const PROVIDER_FULFILLMENT_FACT_SOURCES = [
+  "provider_webhook",
+  "provider_reconciliation",
+  "provider_response",
+] as const;
+/** @beta */ export const FULFILLMENT_FACT_SOURCES = [
+  ...PROVIDER_FULFILLMENT_FACT_SOURCES,
+  "operator_repair",
+] as const;
+/** @beta */ export const FULFILLMENT_FACT_SOURCE_AUTHORITIES = [
+  "provider_asserted",
+  "operator_asserted",
+] as const;
+/** @beta */ export type ProviderFulfillmentFactSource =
+  (typeof PROVIDER_FULFILLMENT_FACT_SOURCES)[number];
+/** @beta */ export type FulfillmentFactSource = (typeof FULFILLMENT_FACT_SOURCES)[number];
+/** @beta */ export type FulfillmentFactSourceAuthority =
+  (typeof FULFILLMENT_FACT_SOURCE_AUTHORITIES)[number];
+/** @beta */ export type FulfillmentFactProvenance =
+  | { readonly source: ProviderFulfillmentFactSource; readonly authority: "provider_asserted" }
+  | { readonly source: "operator_repair"; readonly authority: "operator_asserted" };
+
+/**
+ * Pointer to separately governed raw evidence. The reference is minted by the
+ * adopting application (`evidence:<uuid>`), never copied from provider,
+ * tracking, customer, or order data. PII safety still belongs to that minting
+ * boundary and the referenced evidence store; this contract only enforces the
+ * namespace and identifier shape.
+ */
+/** @beta */ export interface FulfillmentRawEventReference {
+  readonly reference: `evidence:${string}`;
+  readonly digestAlgorithm: "sha256";
+  readonly digest: string;
+}
+
+/** Comparable only within one provider + fulfillment reference sequence. */
+/** @beta */ export interface FulfillmentProviderSequence {
+  readonly kind: "monotonic_ordinal";
+  readonly ordinal: number;
+}
+
+interface NormalizedFulfillmentFactFields<TCanonicalStatus extends string> {
+  readonly mapperVersion: string;
+  readonly factId: string;
+  readonly providerKind: string;
+  readonly fulfillmentReference: string;
+  readonly canonicalStatus: TCanonicalStatus;
+  readonly provenance: FulfillmentFactProvenance;
+  readonly occurredAt: string | null;
+  readonly receivedAt: string;
+  readonly providerSequence?: FulfillmentProviderSequence;
+}
+
+/** Provider-neutral evidence; it authorizes no transition or external effect. */
+/** @beta */ export interface NormalizedFulfillmentFactV1<TCanonicalStatus extends string = string>
+  extends NormalizedFulfillmentFactFields<TCanonicalStatus> {
+  readonly schemaVersion: typeof NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION;
+  readonly rawEvent: FulfillmentRawEventReference;
+}
+
+/** @beta */ export type NormalizedFulfillmentFact<TCanonicalStatus extends string = string> =
+  NormalizedFulfillmentFactV1<TCanonicalStatus>;
+
+/** Narrow legacy wire shape supported only for deterministic N-1 ingestion. */
+/** @beta */ export interface NormalizedFulfillmentFactV0<TCanonicalStatus extends string = string>
+  extends NormalizedFulfillmentFactFields<TCanonicalStatus> {
+  readonly schemaVersion: typeof NORMALIZED_FULFILLMENT_FACT_PREVIOUS_SCHEMA_VERSION;
+  readonly rawEventReference: `evidence:${string}`;
+  readonly rawEventSha256: string;
+}
+
+/** @beta */ export type CompatibleNormalizedFulfillmentFact<TCanonicalStatus extends string = string> =
+  | NormalizedFulfillmentFactV0<TCanonicalStatus>
+  | NormalizedFulfillmentFactV1<TCanonicalStatus>;
+/** @beta */ export interface FulfillmentFactParserOptions<TCanonicalStatus extends string> {
+  isCanonicalStatus(value: string): value is TCanonicalStatus;
+}
+
+const nonEmpty = z.string().trim().min(1);
+const opaqueId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u);
+const evidenceReference = z.string().regex(
+  /^evidence:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u,
+  "must be an application-minted evidence:<uuid> reference",
+);
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/u);
+const rfc3339 = z.iso.datetime({ offset: true });
+const providerProvenance = z.object({
+  source: z.enum(PROVIDER_FULFILLMENT_FACT_SOURCES),
+  authority: z.literal("provider_asserted"),
+}).strict();
+const operatorProvenance = z.object({
+  source: z.literal("operator_repair"),
+  authority: z.literal("operator_asserted"),
+}).strict();
+const provenance = z.union([providerProvenance, operatorProvenance]);
+const providerSequence = z.object({
+  kind: z.literal("monotonic_ordinal"),
+  ordinal: z.number().int().nonnegative().safe(),
+}).strict();
+const commonFields = {
+  mapperVersion: nonEmpty,
+  factId: opaqueId,
+  providerKind: opaqueId,
+  fulfillmentReference: opaqueId,
+  canonicalStatus: nonEmpty,
+  provenance,
+  occurredAt: rfc3339.nullable(),
+  receivedAt: rfc3339,
+  providerSequence: providerSequence.optional(),
+} as const;
+const v1Schema = z.object({
+  schemaVersion: z.literal(NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION),
+  ...commonFields,
+  rawEvent: z.object({
+    reference: evidenceReference,
+    digestAlgorithm: z.literal("sha256"),
+    digest: sha256,
+  }).strict(),
+}).strict();
+const v0Schema = z.object({
+  schemaVersion: z.literal(NORMALIZED_FULFILLMENT_FACT_PREVIOUS_SCHEMA_VERSION),
+  ...commonFields,
+  rawEventReference: evidenceReference,
+  rawEventSha256: sha256,
+}).strict();
+
+/** @beta */ export class InvalidFulfillmentFactError extends Error {
+  constructor(readonly reason: string) {
+    super(`invalid_fulfillment_fact:${reason}`);
+    this.name = "InvalidFulfillmentFactError";
+  }
+}
+
+/** @beta */ export class UnsupportedFulfillmentFactSchemaError extends Error {
+  constructor(readonly schemaVersion: unknown) {
+    super(`unsupported_fulfillment_fact_schema:${String(schemaVersion)}`);
+    this.name = "UnsupportedFulfillmentFactSchemaError";
+  }
+}
+
+/** Strict public unknown-input boundary for current N and supported N-1. */
+/** @beta */ export function parseNormalizedFulfillmentFact<TCanonicalStatus extends string>(
+  value: unknown,
+  options: FulfillmentFactParserOptions<TCanonicalStatus>,
+): NormalizedFulfillmentFact<TCanonicalStatus> {
+  const version = value && typeof value === "object"
+    ? (value as { schemaVersion?: unknown }).schemaVersion
+    : undefined;
+  const schema = version === NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION
+    ? v1Schema
+    : version === NORMALIZED_FULFILLMENT_FACT_PREVIOUS_SCHEMA_VERSION
+      ? v0Schema
+      : null;
+  if (!schema) throw new UnsupportedFulfillmentFactSchemaError(version);
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) throw new InvalidFulfillmentFactError(parsed.error.issues[0]?.message ?? "schema");
+  if (!options.isCanonicalStatus(parsed.data.canonicalStatus)) {
+    throw new InvalidFulfillmentFactError("canonical_status_unknown");
+  }
+  if (parsed.data.schemaVersion === NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION) {
+    return parsed.data as NormalizedFulfillmentFact<TCanonicalStatus>;
+  }
+  const { rawEventReference, rawEventSha256, ...shared } = parsed.data;
+  return {
+    ...shared,
+    schemaVersion: NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION,
+    canonicalStatus: parsed.data.canonicalStatus,
+    rawEvent: {
+      reference: rawEventReference,
+      digestAlgorithm: "sha256",
+      digest: rawEventSha256,
+    },
+  } as NormalizedFulfillmentFact<TCanonicalStatus>;
+}
+
+/** Stable property-order-independent identity of one already parsed fact. */
+/** @beta */ export function canonicalFulfillmentFactFingerprint(
+  fact: NormalizedFulfillmentFact,
+): string {
+  return JSON.stringify([
+    fact.schemaVersion,
+    fact.mapperVersion,
+    fact.factId,
+    fact.providerKind,
+    fact.fulfillmentReference,
+    fact.canonicalStatus,
+    fact.provenance.source,
+    fact.provenance.authority,
+    fact.occurredAt,
+    fact.receivedAt,
+    fact.providerSequence?.kind ?? null,
+    fact.providerSequence?.ordinal ?? null,
+    fact.rawEvent.reference,
+    fact.rawEvent.digestAlgorithm,
+    fact.rawEvent.digest,
+  ]);
+}
+
+/** @beta */ export class FulfillmentFactCollisionError extends Error {
+  constructor(readonly factId: string) {
+    super(`fulfillment_fact_id_collision:${factId}`);
+    this.name = "FulfillmentFactCollisionError";
+  }
+}
+
+/** Deterministic exact-duplicate collapse; conflicting reuse fails closed. */
+/** @beta */ export function canonicalizeFulfillmentFacts<TCanonicalStatus extends string>(
+  facts: readonly NormalizedFulfillmentFact<TCanonicalStatus>[],
+): NormalizedFulfillmentFact<TCanonicalStatus>[] {
+  const byId = new Map<string, { fact: NormalizedFulfillmentFact<TCanonicalStatus>; fingerprint: string }>();
+  for (const fact of facts) {
+    const fingerprint = canonicalFulfillmentFactFingerprint(fact);
+    const existing = byId.get(fact.factId);
+    if (existing && existing.fingerprint !== fingerprint) throw new FulfillmentFactCollisionError(fact.factId);
+    byId.set(fact.factId, { fact, fingerprint });
+  }
+  return [...byId.values()]
+    .sort((left, right) => left.fact.factId.localeCompare(right.fact.factId))
+    .map(({ fact }) => fact);
+}
+
+/** @beta */ export const TRANSITION_CONFLICT_REASONS = [
+  "status_regression",
+  "terminal_status_disagreement",
+  "provider_sequence_regression",
+  "source_authority_disagreement",
+] as const;
+/** @beta */ export type TransitionConflictReason = (typeof TRANSITION_CONFLICT_REASONS)[number];
+
+/** @beta */ export interface FulfillmentTransitionSnapshot<TCanonicalStatus extends string = string> {
+  readonly fact: NormalizedFulfillmentFact<TCanonicalStatus>;
+}
+
+/** @beta */ export type TransitionConflictDecision =
+  | { readonly kind: "selected"; readonly selected: "current" | "incoming"; readonly reasonCode: string }
+  | { readonly kind: "hold"; readonly reasonCode: string };
+
+/** Self-contained immutable diagnostic emitted by a future consumer reducer. */
+/** @beta */ export interface TransitionConflict<TCanonicalStatus extends string = string> {
+  readonly conflictId: `conflict:${string}`;
+  readonly policyVersion: string;
+  readonly reason: TransitionConflictReason;
+  readonly fulfillmentReference: string;
+  readonly current: FulfillmentTransitionSnapshot<TCanonicalStatus>;
+  readonly incoming: FulfillmentTransitionSnapshot<TCanonicalStatus>;
+  readonly decision: TransitionConflictDecision;
+  readonly detectedAt: string;
+}
+
+const conflictReference = z.string().regex(
+  /^conflict:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u,
+  "must be an application-minted conflict:<uuid> reference",
+);
+const transitionConflictEnvelope = z.object({
+  conflictId: conflictReference,
+  policyVersion: nonEmpty,
+  reason: z.enum(TRANSITION_CONFLICT_REASONS),
+  fulfillmentReference: opaqueId,
+  current: z.object({ fact: z.unknown() }).strict(),
+  incoming: z.object({ fact: z.unknown() }).strict(),
+  decision: z.discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("selected"),
+      selected: z.enum(["current", "incoming"]),
+      reasonCode: opaqueId,
+    }).strict(),
+    z.object({ kind: z.literal("hold"), reasonCode: opaqueId }).strict(),
+  ]),
+  detectedAt: rfc3339,
+}).strict();
+
+/** @beta */ export function parseTransitionConflict<TCanonicalStatus extends string>(
+  value: unknown,
+  options: FulfillmentFactParserOptions<TCanonicalStatus>,
+): TransitionConflict<TCanonicalStatus> {
+  const envelope = transitionConflictEnvelope.safeParse(value);
+  if (!envelope.success) {
+    throw new InvalidFulfillmentFactError(
+      `transition_conflict:${envelope.error.issues[0]?.message ?? "schema"}`,
+    );
+  }
+  const current = parseNormalizedFulfillmentFact(envelope.data.current.fact, options);
+  const incoming = parseNormalizedFulfillmentFact(envelope.data.incoming.fact, options);
+  if (current.providerKind !== incoming.providerKind
+    || current.fulfillmentReference !== incoming.fulfillmentReference
+    || envelope.data.fulfillmentReference !== current.fulfillmentReference) {
+    throw new InvalidFulfillmentFactError("transition_conflict_stream_mismatch");
+  }
+  return {
+    ...envelope.data,
+    conflictId: envelope.data.conflictId as `conflict:${string}`,
+    decision: envelope.data.decision!,
+    current: { fact: current },
+    incoming: { fact: incoming },
+  };
+}

package/src/fulfillment/index.ts

@@ -0,0 +1,34 @@
+/** @beta */
+export {
+  FULFILLMENT_FACT_SOURCE_AUTHORITIES,
+  FULFILLMENT_FACT_SOURCES,
+  PROVIDER_FULFILLMENT_FACT_SOURCES,
+  NORMALIZED_FULFILLMENT_FACT_PREVIOUS_SCHEMA_VERSION,
+  NORMALIZED_FULFILLMENT_FACT_SCHEMA_VERSION,
+  TRANSITION_CONFLICT_REASONS,
+  InvalidFulfillmentFactError,
+  FulfillmentFactCollisionError,
+  UnsupportedFulfillmentFactSchemaError,
+  canonicalFulfillmentFactFingerprint,
+  canonicalizeFulfillmentFacts,
+  parseNormalizedFulfillmentFact,
+  parseTransitionConflict,
+} from "./facts.js";
+/** @beta */
+export type {
+  CompatibleNormalizedFulfillmentFact,
+  FulfillmentFactSourceAuthority,
+  FulfillmentFactSource,
+  FulfillmentFactProvenance,
+  FulfillmentRawEventReference,
+  FulfillmentProviderSequence,
+  FulfillmentFactParserOptions,
+  ProviderFulfillmentFactSource,
+  NormalizedFulfillmentFact,
+  NormalizedFulfillmentFactV0,
+  NormalizedFulfillmentFactV1,
+  TransitionConflict,
+  TransitionConflictDecision,
+  FulfillmentTransitionSnapshot,
+  TransitionConflictReason,
+} from "./facts.js";

package/src/inventory/atp.ts

@@ -0,0 +1,249 @@
+import { z } from "zod";
+
+/** @beta */
+export const INVENTORY_CONTRACT_VERSION = "inventory.v0";
+
+const uuidSchema = z.guid();
+const datetimeSchema = z.string().datetime({ offset: true });
+const quantitySchema = z.number().int().nonnegative();
+const positiveQuantitySchema = z.number().int().positive();
+
+/** @beta */
+export const inventoryLocationKindSchema = z.enum([
+  "internal_warehouse",
+  "third_party_logistics",
+  "supplier",
+  "quarantine",
+  "virtual",
+]);
+/** @beta */
+export const inventoryLocationStatusSchema = z.enum(["active", "inactive"]);
+/** @beta */
+export const inventoryLotStatusSchema = z.enum(["available", "quarantined", "expired", "recalled"]);
+/** @beta */
+export const inventoryAtpStatusSchema = z.enum(["fulfillable", "insufficient", "review_required", "unsupported"]);
+
+/** @beta */
+export const inventoryStockLineSchema = z.object({
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  locationId: uuidSchema,
+  locationCode: z.string().trim().min(1),
+  locationKind: inventoryLocationKindSchema,
+  locationStatus: inventoryLocationStatusSchema,
+  fulfillable: z.boolean(),
+  lotId: uuidSchema.nullable(),
+  lotCode: z.string().trim().min(1).nullable(),
+  lotStatus: inventoryLotStatusSchema.nullable(),
+  expiresAt: datetimeSchema.nullable(),
+  onHand: quantitySchema,
+  reserved: quantitySchema,
+  unavailable: quantitySchema,
+  incoming: quantitySchema,
+  safetyStock: quantitySchema,
+}).strict();
+
+/** @beta */
+export const inventoryAtpRequestLineSchema = z.object({
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  quantity: positiveQuantitySchema,
+}).strict();
+
+/** @beta */
+export const inventoryAtpRequestSchema = z.object({
+  contractVersion: z.literal(INVENTORY_CONTRACT_VERSION),
+  lines: z.array(inventoryAtpRequestLineSchema).min(1),
+  requestedAt: datetimeSchema,
+  orderMode: z.enum(["one_time", "subscription_cycle"]),
+  region: z.string().trim().min(2).max(32).optional(),
+  noSplitShipment: z.boolean().default(true),
+  minShelfLifeDays: z.number().int().min(0).max(730).default(0),
+}).strict();
+
+/** @beta */
+export const inventoryAllocationSchema = z.object({
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  locationId: uuidSchema,
+  locationCode: z.string().trim().min(1),
+  lotId: uuidSchema.nullable(),
+  lotCode: z.string().trim().min(1).nullable(),
+  quantity: positiveQuantitySchema,
+  expiresAt: datetimeSchema.nullable(),
+}).strict();
+
+/** @beta */
+export const inventoryAtpLineResultSchema = z.object({
+  skuId: uuidSchema,
+  sku: z.string().trim().min(1),
+  requestedQuantity: positiveQuantitySchema,
+  availableQuantity: quantitySchema,
+  missingQuantity: quantitySchema,
+  status: inventoryAtpStatusSchema,
+  allocations: z.array(inventoryAllocationSchema),
+}).strict();
+
+/** @beta */
+export const inventoryAtpResultSchema = z.object({
+  contractVersion: inventoryAtpRequestSchema.shape.contractVersion,
+  status: inventoryAtpStatusSchema,
+  reason: z.string().trim().min(1).nullable(),
+  locationId: uuidSchema.nullable(),
+  locationCode: z.string().trim().min(1).nullable(),
+  lines: z.array(inventoryAtpLineResultSchema),
+}).strict();
+
+/** @beta */
+export type InventoryAtpRequest = z.input<typeof inventoryAtpRequestSchema>;
+/** @beta */
+export type InventoryAtpResult = z.infer<typeof inventoryAtpResultSchema>;
+/** @beta */
+export type InventoryStockLine = z.infer<typeof inventoryStockLineSchema>;
+
+/** @beta */
+export interface CalculateInventoryAtpInput {
+  request: InventoryAtpRequest;
+  stock: InventoryStockLine[];
+}
+
+/** @beta */
+export function availableNow(line: Pick<InventoryStockLine, "onHand" | "reserved" | "unavailable" | "safetyStock">): number {
+  return Math.max(0, line.onHand - line.reserved - line.unavailable - line.safetyStock);
+}
+
+/** @beta */
+export function calculateInventoryAtp(input: CalculateInventoryAtpInput): InventoryAtpResult {
+  if (input.request.noSplitShipment === false) {
+    return inventoryAtpResultSchema.parse({
+      contractVersion: INVENTORY_CONTRACT_VERSION,
+      status: "unsupported",
+      reason: "split_shipment_unsupported",
+      locationId: null,
+      locationCode: null,
+      lines: input.request.lines.map((line) => ({
+        skuId: line.skuId,
+        sku: line.sku,
+        requestedQuantity: line.quantity,
+        availableQuantity: 0,
+        missingQuantity: line.quantity,
+        status: "unsupported",
+        allocations: [],
+      })),
+    });
+  }
+
+  const usableStock = input.stock.filter((line) => isUsable(
+    line,
+    input.request.requestedAt,
+    input.request.minShelfLifeDays ?? 0,
+  ));
+  const locationIds = [...new Set(usableStock.map((line) => line.locationId))];
+  const preferredLocation = locationIds
+    .map((locationId) => allocationForLocation(input.request, usableStock, locationId))
+    .find((candidate) => candidate.status === "fulfillable");
+
+  if (preferredLocation) {
+    return inventoryAtpResultSchema.parse({
+      contractVersion: INVENTORY_CONTRACT_VERSION,
+      status: "fulfillable",
+      reason: null,
+      locationId: preferredLocation.locationId,
+      locationCode: preferredLocation.locationCode,
+      lines: preferredLocation.lines,
+    });
+  }
+
+  const lines = input.request.lines.map((requestLine) => {
+    const matching = usableStock.filter((line) => line.skuId === requestLine.skuId);
+    const availableQuantity = matching.reduce((sum, line) => sum + availableNow(line), 0);
+    return {
+      skuId: requestLine.skuId,
+      sku: requestLine.sku,
+      requestedQuantity: requestLine.quantity,
+      availableQuantity,
+      missingQuantity: Math.max(0, requestLine.quantity - availableQuantity),
+      status: availableQuantity >= requestLine.quantity ? "review_required" : "insufficient",
+      allocations: [],
+    };
+  });
+
+  const hasEnoughInAggregate = lines.every((line) => line.missingQuantity === 0);
+  return inventoryAtpResultSchema.parse({
+    contractVersion: INVENTORY_CONTRACT_VERSION,
+    status: hasEnoughInAggregate ? "review_required" : "insufficient",
+    reason: hasEnoughInAggregate
+      ? "stock_available_only_with_split_shipment"
+      : "insufficient_available_stock",
+    locationId: null,
+    locationCode: null,
+    lines,
+  });
+}
+
+function allocationForLocation(
+  request: InventoryAtpRequest,
+  stock: InventoryStockLine[],
+  locationId: string,
+) {
+  const locationStock = stock.filter((line) => line.locationId === locationId);
+  const locationCode = locationStock[0]?.locationCode ?? null;
+  const lines = request.lines.map((requestLine) => {
+    let remaining = requestLine.quantity;
+    const allocations = locationStock
+      .filter((line) => line.skuId === requestLine.skuId && availableNow(line) > 0)
+      .sort(fefoSort)
+      .flatMap((line) => {
+        if (remaining <= 0) return [];
+        const quantity = Math.min(remaining, availableNow(line));
+        remaining -= quantity;
+        return [{
+          skuId: requestLine.skuId,
+          sku: requestLine.sku,
+          locationId: line.locationId,
+          locationCode: line.locationCode,
+          lotId: line.lotId,
+          lotCode: line.lotCode,
+          quantity,
+          expiresAt: line.expiresAt,
+        }];
+      });
+
+    return {
+      skuId: requestLine.skuId,
+      sku: requestLine.sku,
+      requestedQuantity: requestLine.quantity,
+      availableQuantity: requestLine.quantity - remaining,
+      missingQuantity: remaining,
+      status: remaining === 0 ? "fulfillable" : "insufficient",
+      allocations,
+    };
+  });
+
+  return {
+    status: lines.every((line) => line.status === "fulfillable") ? "fulfillable" : "insufficient",
+    locationId,
+    locationCode,
+    lines,
+  };
+}
+
+function isUsable(line: InventoryStockLine, requestedAt: string, minShelfLifeDays: number): boolean {
+  if (!line.fulfillable || line.locationStatus !== "active") return false;
+  if (line.lotStatus && line.lotStatus !== "available") return false;
+  if (line.expiresAt && Date.parse(line.expiresAt) <= minAcceptableExpiry(requestedAt, minShelfLifeDays)) {
+    return false;
+  }
+  return availableNow(line) > 0;
+}
+
+function minAcceptableExpiry(requestedAt: string, minShelfLifeDays: number): number {
+  return Date.parse(requestedAt) + minShelfLifeDays * 24 * 60 * 60 * 1000;
+}
+
+function fefoSort(a: InventoryStockLine, b: InventoryStockLine): number {
+  const aExpiry = a.expiresAt ? Date.parse(a.expiresAt) : Number.POSITIVE_INFINITY;
+  const bExpiry = b.expiresAt ? Date.parse(b.expiresAt) : Number.POSITIVE_INFINITY;
+  if (aExpiry !== bExpiry) return aExpiry - bExpiry;
+  return a.locationCode.localeCompare(b.locationCode) || (a.lotCode ?? "").localeCompare(b.lotCode ?? "");
+}

package/src/inventory/index.ts

@@ -0,0 +1,2 @@
+/** @beta */
+export * from "./atp.js";

package/src/marketing/research/contracts.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+
+/** @beta */
+export type MarketingResearchJson =
+  | string
+  | number
+  | boolean
+  | null
+  | { [key: string]: MarketingResearchJson | undefined }
+  | MarketingResearchJson[];
+
+/** @beta */
+export const marketingResearchJsonSchema = z.custom<MarketingResearchJson>(
+  isMarketingResearchJson,
+  { message: "Expected JSON value" },
+);
+
+/** @beta */
+export const researchSurveyTypeSchema = z.enum(["producer", "consumer"]);
+
+/** @beta */
+export const adminSurveyResponsesRequestSchema = z
+  .object({
+    surveyType: researchSurveyTypeSchema,
+    page: z.coerce.number().int().nonnegative().default(0),
+    pageSize: z.coerce.number().int().min(1).max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(500).optional(),
+  })
+  .transform(({ limit, pageSize, ...request }) => ({
+    ...request,
+    pageSize: pageSize ?? Math.min(limit ?? 50, 100),
+  }));
+
+/** @beta */
+export const adminSurveyResponseRowSchema = z.object({
+  id: z.string().min(1),
+  created_at: z.string().min(1),
+  response_data: marketingResearchJsonSchema,
+});
+
+/** @beta */
+export const adminSurveyResponsesResponseSchema = z.object({
+  rows: z.array(adminSurveyResponseRowSchema),
+  totalCount: z.number().int().nonnegative(),
+  page: z.number().int().nonnegative(),
+  pageSize: z.number().int().positive(),
+});
+
+/** @beta */
+export const researchSurveySubmitRequestSchema = z
+  .object({
+    surveyType: researchSurveyTypeSchema,
+    responseData: z.record(z.string(), marketingResearchJsonSchema),
+  })
+  .refine((request) => Object.keys(request.responseData).length > 0, {
+    message: "responseData must not be empty",
+    path: ["responseData"],
+  });
+
+/** @beta */
+export const researchSurveySubmitResponseSchema = z.object({
+  ok: z.boolean(),
+  id: z.string().min(1).optional(),
+  error: z.string().optional(),
+  email_skipped: z.string().optional(),
+});
+
+/** @beta */
+export type ResearchSurveyType = z.infer<typeof researchSurveyTypeSchema>;
+/** @beta */
+export type AdminSurveyResponsesRequest = z.infer<typeof adminSurveyResponsesRequestSchema>;
+/** @beta */
+export type AdminSurveyResponseRow = z.infer<typeof adminSurveyResponseRowSchema>;
+/** @beta */
+export type AdminSurveyResponsesResponse = z.infer<typeof adminSurveyResponsesResponseSchema>;
+/** @beta */
+export type ResearchSurveySubmitRequest = z.infer<typeof researchSurveySubmitRequestSchema>;
+/** @beta */
+export type ResearchSurveySubmitResponse = z.infer<typeof researchSurveySubmitResponseSchema>;
+
+function isMarketingResearchJson(value: unknown): value is MarketingResearchJson {
+  if (value === null) return true;
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isMarketingResearchJson);
+  if (typeof value !== "object") return false;
+
+  return Object.values(value as Record<string, unknown>).every(
+    (entry) => entry === undefined || isMarketingResearchJson(entry),
+  );
+}

package/src/marketing/research/index.ts

@@ -0,0 +1,4 @@
+/** @beta */
+export * from "./contracts.js";
+/** @beta */
+export * from "./ports.js";