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.key,
    keys: null,
    site: 'site/tutorial/steps/05-optimistic/src/app.tsx:addToCart',
    via: 'cart_items',
  },
  {
    domain: product.key,
    keys: 'arg:productId',
    predicate: 'eq',
    site: 'site/tutorial/steps/05-optimistic/src/app.tsx:addToCart',
    via: 'products',
  },
] as const;

export const cartQuery = app.query({
  access: app.publicAccess('tutorial single-cart storefront read'),
  load: (_input, context) => loadCart(tutorialShopDb(context.request).query.snapshot()),
  reads: [cart],
});

export const productsQuery = app.query({
  access: app.publicAccess('tutorial public product catalog'),
  load: (_input, context) => loadProducts(tutorialShopDb(context.request).query.snapshot()),
  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=${cartQuery.key}; product-list=${productsQuery.key}`,
    },
  );
  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="${cartQuery.key}">{"count":2}</kovo-query>`);
  expect(response.body).toContain(`<kovo-query name="${productsQuery.key}">`);
  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.key}"},{"domain":"${product.key}"}]`,
  );
});

// SPEC.md section 10.4: optimism is keyed to queries, never islands. The
// cart count is predictable from the input alone — a pure value 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. Query handles bind both decisions to their
// exact result types; kovo check proves coverage against invalidation.
queue: 'cart',
optimistic: [
  cartQuery.optimistic(addToCartInput, predictCart),
  productsQuery.optimistic('await-fragment'),
],

it('predicts the cart count with the hand-written transform', () => {
  expect(predictCart({ count: 1 }, { productId: 'p1', quantity: 2 })).toEqual({ count: 3 });
});

// 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 predictCart(shapeCartQuery(state), input);
      },
      shape(state) {
        return shapeCartQuery(state);
      },
    }),
  ).toEqual({ cases: 18 });
});