Invalidation & optimistic updates

// SPEC.md section 11.1: with the blessed @kovojs/drizzle adapter these touch
// sites are extracted from the write ASTs and committed as a reviewable
// graph. The tutorial's plain in-memory db has no ASTs to analyze, so it
// declares the touches — the SPEC.md section 14 v1 floor — and chapter 7
// runtime-verifies the declaration against observed writes.
export const addToCartTouches = [
  {
    domain: 'cart',
    keys: null,
    site: 'site/tutorial/steps/05-optimistic/src/app.ts:addToCart',
    via: 'cart_items',
  },
  {
    domain: 'product',
    keys: 'arg:productId',
    predicate: 'eq',
    site: 'site/tutorial/steps/05-optimistic/src/app.ts:addToCart',
    via: 'products',
  },
] as const;

export const cartQuery = query('cart', {
  load: (_input: unknown, context?: QueryLoadContext<ShopRequest>) => loadCart(dbFrom(context)),
  reads: [cart],
});

export const productsQuery = query('products', {
  load: (_input: unknown, context?: QueryLoadContext<ShopRequest>) => loadProducts(dbFrom(context)),
  reads: [product],
});

it('derives the queries to re-run and ships server truth on the wire', async () => {
  const request = shopRequest();
  const response = await submitAddToCart(
    formInput(request, { productId: 'p1', quantity: '2' }),
    request,
    {
      'Kovo-Fragment': 'true',
      'Kovo-Live-Targets':
        'cart-badge#components/cart-badge/cart-badge:{}; product-list#components/product-list/product-list:{}',
      'Kovo-Targets': 'cart-badge=cart; product-list=products',
    },
  );

  expect(response.status).toBe(200);
  // Server truth for every invalidated query, as readable chunks: the
  // loader replaces each value and runs its update plan (SPEC.md §9.1).
  expect(response.body).toContain('<kovo-query name="cart">{"count":2}</kovo-query>');
  expect(response.body).toContain('<kovo-query name="products">');
  expect(response.body).toContain('<kovo-fragment target="cart-badge">');
  expect(response.body).toContain('<kovo-fragment target="product-list">');
  // The sanitized write summary: domains and keys, never input values.
  expect(response.headers['Kovo-Changes']).toBe(
    '[{"domain":"cart"},{"domain":"product","keys":["p1"]}]',
  );
});

// SPEC.md section 10.4: optimism is keyed to queries, never islands. The
// cart count is predictable from the input alone — a pure transform. The
// product list depends on server truth (stock math lives in the handler), so
// it explicitly accepts the 1-RTT fragment: 'await-fragment' is a recorded
// decision, not an omission. tsc requires an entry per invalidated query
// (section 10.6) — delete one and this satisfies clause turns red.
export const addToCartOptimistic = {
  queue: 'cart',
  transforms: {
    cart(current, input) {
      return {
        count: (current?.count ?? 0) + input.quantity,
      };
    },
    products: 'await-fragment',
  },
} satisfies OptimisticFor<typeof addToCartForm>;

declare module '@kovojs/core' {
  interface QueryRegistry {
    cart: CartResult;
    products: ProductsResult;
  }

  interface MutationRegistry {
    'cart/add': typeof import('./app.js').addToCart;
  }

  interface InvalidationSets {
    'cart/add': 'cart' | 'products';
  }
}

it('predicts the cart count with the hand-written transform', () => {
  expect(addToCartOptimistic.queue).toBe('cart');
  expect(
    addToCartOptimistic.transforms.cart({ count: 1 }, { productId: 'p1', quantity: 2 }),
  ).toEqual({ count: 3 });
  // Every invalidated query has an explicit status (SPEC.md §10.6).
  expect(Object.keys(addToCartOptimistic.transforms).sort()).toEqual(['cart', 'products']);
  expect(addToCartOptimistic.transforms.products).toBe('await-fragment');
});

// The real write effect, restated over plain state: what the handler commits.
function applyAddToCart(state: ShopPropertyState, input: AddToCartInput): ShopPropertyState {
  const found = state.products[input.productId];
  if (!found || found.stock < input.quantity) {
    throw new Error(`invalid property case for ${input.productId}`);
  }

  return {
    cartItems: [...state.cartItems, { productId: input.productId, qty: input.quantity }],
    products: {
      ...state.products,
      [input.productId]: { stock: found.stock - input.quantity },
    },
  };
}

// What the cart query ships to the client for a given state.
function shapeCartQuery(state: ShopPropertyState): { count: number } {
  return { count: state.cartItems.reduce((total, item) => total + item.qty, 0) };
}

it('proves prediction ⊆ eventual truth over generated states', () => {
  expect(
    propertyTest<ShopPropertyState, AddToCartInput, { count: number }>({
      apply(state, input) {
        return applyAddToCart(state, input);
      },
      cases: propertyCases(),
      predict(state, input) {
        return addToCartOptimistic.transforms.cart(shapeCartQuery(state), input);
      },
      shape(state) {
        return shapeCartQuery(state);
      },
    }),
  ).toEqual({ cases: 18 });
});