northcinder 买家侧 Agent 商务防线

22/** Durable record of an authorized checkout, citing the mandate that gated it. */
23export interface OrderRecord {
24  orderId: string;
25  createdAt: string;
26  offerId: string;
27  merchantId: string;
28  /** Canonical merchant domain paired with merchantId to avoid local-history collisions. */
29  merchantDomain: string;
30  railId: string;
31  /** "completed" = purchase made by the rail; "handed_off" = user's own session completes it. */
32  status: "completed" | "handed_off";
33  /** The mandate that authorized this checkout (cited in full for audit). */
34  mandateId: string;
35  mandate: PurchaseMandate;
36  evidence: RailEvidence;
37}
38
39export type CheckoutOutcome =
40  | { ok: true; order: OrderRecord }
41  | { ok: false; stage: "mandate"; error: MandateRejection }
42  | { ok: false; stage: "rail"; error: CheckoutError };

339  function finalizeSearch(params: {
340    searchId: string;
341    interpreted: InterpretedQuery;
342    data: SearchRankResponse;
343    continuedFrom?: string;
344  }) {
345    const { searchId, interpreted, continuedFrom } = params;
346    const parsedData = SearchRankResponseSchema.safeParse(params.data);
347    if (!parsedData.success) {
348      return failure({
349        code: "invalid_service_response",
350        message: "configured engine returned an invalid search response",
351      });
352    }
353    const data = parsedData.data;
354    const query = interpreted.criteria;
355    const { results, storeStatuses, trustSignals, registeredStores, browserObservationReport } = data;
356
357    seenSearches.set(searchId, interpreted);
358
359    for (const r of results) {
360      seenOffers.set(offerKey(r.offer.sourceStore, r.offer.id), r.offer);
361      const merchantKey = trustKey(r.offer.merchant);
362      seenMerchants.set(merchantKey, r.offer.merchant);
363      const keys = seenMerchantKeysById.get(r.offer.merchant.id) ?? new Set<string>();
364      keys.add(merchantKey);
365      seenMerchantKeysById.set(r.offer.merchant.id, keys);
366    }
367
368    const verification = verifySearchRanking(data, query);
369    const coverage = verifyStoreCoverage(registeredStores, storeStatuses);
370    const brief = composeBuyersBrief({
371      searchId,
372      results,
373      interpretedQuery: interpreted,
374      storeStatuses,
375      trustSignals,
376    });
377    seenBriefs.set(searchId, brief);
378
379    const localTrustEvidence: Record<string, ReturnType<typeof localTrustEvidenceFor>> = {};
380    const localTrustEvidenceKeys: Record<string, string> = {};
381    for (const f of brief.finalists) {
382      const finalistKey = offerKey(f.sourceStore, f.offerId);
383      const fullMerchant = seenOffers.get(finalistKey)?.merchant;
384      if (!fullMerchant) continue;
385      const merchantKey = trustKey(fullMerchant);
386      localTrustEvidenceKeys[finalistKey] = merchantKey;

240    /** Fingerprint over the canonical tuple AS DISPLAYED to the human. */
241    fingerprint: string;
242    /**
243     * Private request-time snapshot of the WHOLE offer as displayed to the
244     * human. approve() deep-compares the live offer against it (catches
245     * mutation of ANY field — incl. product.id, variant gid, title — not
246     * just the fingerprinted ones), and checkout reads THIS, never the
247     * externally-reachable live object.
248     */
249    offerSnapshot: Offer;
250    /** Snapshot of the cap shown on the trusted channels (mutation-detected at approve). */
251    approvedCap: Money;
252    /** Snapshot of the intent line the human read (mutation-detected at approve). */
253    intentSnapshot: string;
254    /** True while a checkout attempt is executing (decline is refused then). */
255    checkoutInFlight: boolean;
256  }
257  const records = new Map<string, InternalRecord>();
258
259  /** Fingerprint over the authorization's CURRENT tuple + the issuance nonce. */
260  function currentFingerprint(auth: Authorization, nonce: string): string {
261    const total = offerTotal(auth.offer);
262    return orderFingerprint({
263      merchantId: auth.offer.merchant.id,
264      offerId: auth.offer.id,
265      // Bind the PURCHASE-relevant identities, not just the offer id: the
266      // ACP rail buys by product.id, cart-permalink by the variant gid.
267      productId: auth.offer.product.id,
268      variantKey: auth.offer.product.attributes[VARIANT_ATTRIBUTE] ?? "",
269      totalMinor: total.amount,
270      currency: total.currency,
271      nonce,
272    });
273  }
274
275  /**
276   * Defensive read view (the CHECKOUT door): a deep clone whose offer and cap
277   * come from the private request-time snapshots — approve-time truth, never
278   * the externally-reachable live object. Post-approve mutation of a held
279   * reference therefore cannot re-aim what checkout verifies or charges.
280   */
281  function snapshotView(record: InternalRecord): Authorization {
282    return {
283      ...structuredClone(record.authorization),
284      offer: structuredClone(record.offerSnapshot),
285      maxAmount: structuredClone(record.approvedCap),
286      intent: record.intentSnapshot,
287    };
288  }
289
290  function expireIfDue(record: InternalRecord): void {
291    const auth = record.authorization;
292    if (auth.status === "pending" && now().getTime() > new Date(auth.expiresAt).getTime()) {
293      auth.status = "expired";
294      rmSync(record.codeFile, { force: true });
295    }
296  }
297
298  return {
299    request(offer, opts) {
300      const at = now();
301      const id = `auth_${randomUUID()}`;
302      // Own copies: the authorization's tuple must not alias caller-held
303      // objects (a later caller-side mutation must not silently retarget it).
304      const ownOffer = structuredClone(offer);
305      const maxAmount = structuredClone(opts.maxAmount ?? offerTotal(offer));
306      const paymentContext = opts.paymentContext ?? "none";
307      const authorization: Authorization = {
308        id,
309        status: "pending",
310        offer: ownOffer,
311        intent: opts.intent,
312        maxAmount,
313        paymentContext,
314        createdAt: at.toISOString(),
315        expiresAt: new Date(at.getTime() + ttlMs).toISOString(),

112      error: {
113        code: "invalid_service_response",
114        message: "configured engine returned an invalid search response",
115      },
116    });
117    expect(existsSync(auditPath) ? readFileSync(auditPath, "utf8") : "").toBe(auditBefore);
118
119    const authorization = await client.callTool({
120      name: "request_purchase_authorization",
121      arguments: { offerId: provenanceStrippedBrowser.id, sourceStore: provenanceStrippedBrowser.sourceStore },
122    });
123    expect(JSON.parse((authorization.content as Array<{ text: string }>)[0]!.text)).toMatchObject({
124      error: { code: "unknown_offer" },
125    });
126    await client.close();
127  });
128
129  it("an HONEST service is verified: rankingVerified true in output and audit log", async () => {
130    const honest: SearchRankResponse = {
131      results: rankOffers(OFFERS, { text: "sneaker" }, { trust: TRUST }),
132      storeStatuses: STORE_STATUSES,
133      trustSignals: TRUST,
134    };
135    const { client, auditPath } = await connectedClient(serviceReturning(honest));
136    const result = await client.callTool({ name: "search_products", arguments: { text: "sneaker" } });
137    expect(result.isError ?? false).toBe(false);
138    const structured = result.structuredContent as { rankingVerified: unknown; rankingDivergences?: unknown };
139    expect(structured.rankingVerified).toBe(true);
140    expect(structured.rankingDivergences).toBeUndefined();
141    const text = (result.content as Array<{ text: string }>)[0]!.text;
142    expect(text).toContain("Ranking verified");
143    expect(text).not.toContain(RANKING_TAMPER_WARNING);
144
145    const search = auditSearchLine(auditPath);
146    expect(search.rankingVerified).toBe(true);
147    await client.close();
148  });
149
150  it("TAMPER: a fake service returning a boosted re-order is flagged rankingVerified false with the exact divergence", async () => {
151    const ranked = rankOffers(OFFERS, { text: "sneaker" }, { trust: TRUST });
152    // Honest order is [cheap, mid, paid] (sponsored strictly last). The tampered
153    // service "boosts" the sponsored offer to the top — the classic pay-for-rank.
154    expect(ranked.map((r) => r.offer.id)).toEqual(["cheap", "mid", "paid"]);
155    const boosted: SearchRankResponse = {
156      results: [ranked[2]!, ranked[0]!, ranked[1]!],
157      storeStatuses: STORE_STATUSES,
158      trustSignals: TRUST,
159    };
160    const { client, auditPath } = await connectedClient(serviceReturning(boosted));
161    const result = await client.callTool({ name: "search_products", arguments: { text: "sneaker" } });
162    expect(result.isError ?? false).toBe(false); // results still returned — but loudly flagged
163
164    const structured = result.structuredContent as {
165      rankingVerified: unknown;
166      rankingDivergences?: Array<{ kind: string; position: number; expected: { offerKey: string }; actual: { offerKey: string } }>;
167    };
168    expect(structured.rankingVerified).toBe(false);
169    expect(structured.rankingDivergences).toBeDefined();
170    expect(structured.rankingDivergences![0]).toEqual({
171      kind: "order_mismatch",
172      position: 1,
173      expected: { offerKey: "ebay:cheap", score: ranked[0]!.score },
174      actual: { offerKey: "ebay:paid", score: ranked[2]!.score },