@integraledger/lcp-placement-x402 0.9.0 → 0.11.0

package/src/manifest.ts

@@ -1,53 +1,75 @@
 import type { PlacementManifest } from "@integraledger/lcp-binding-core";
 
 /**
- * The carrier's JSON Schema, INLINED rather than referenced.
+ * The carrier's JSON Schema, INLINED rather than referenced — and equal, member for member, to the
+ * AUTHORITY document at `https://integraledger.com/lcp/x402/legal-context/v1.schema.json` minus its `$id`
+ * and `$defs`. That equality is load-bearing and drift-gated (the conformance suite compares this literal
+ * to `@integraledger/lcp-discovery`'s shipped copy of the authority file), because its absence was a
+ * published defect: from 0.10.1's release until this version, this schema said `required: ["type",
+ * "value"]` while the authority document said `required: ["type", "value", "legalContextUrl"]` — two
+ * definitions of the same `info` in the published ecosystem, self-consistent halves, no document valid
+ * against both (integra-protocol#8). Both being conformant to the schema each carried is exactly why no
+ * package's own tests could catch it; only comparing the two could, and now something does.
  *
- * x402 makes `schema` a REQUIRED member of an extension entry — "JSON Schema defining the expected
- * structure of info" — so whatever goes here is on the wire of every challenge. A `$ref` to a URL nobody
- * serves would be a required member no counterparty can resolve, and "x402 never fetches it" is a reason
- * that does not break, not a reason to ship it. (`https://legalcontextprotocol.org/schemas/lcp-extension.json`
- * returns **404**, measured 2026-08-08 — the schema is inlined instead.)
+ * WHY INLINE AT ALL: x402 makes `schema` a REQUIRED member of an extension entry — "JSON Schema defining
+ * the expected structure of info" — so whatever goes here is on the wire of every challenge. **All nine
+ * extensions published in the x402 repository inline a complete JSON Schema** rather than referencing an
+ * external document (`x402-foundation/x402` HEAD, read 2026-08-11), and one of the nine makes it a rule:
+ * the Bazaar extension requires a `schema`'s `$ref`/`$id` values to be "same-document JSON Pointer
+ * fragments (starting with `#`); external references … are not allowed", and says a facilitator "must not
+ * resolve external `$ref`/`$id` values … when validating an untrusted `schema`". So an external `$ref`
+ * here would not merely be unresolvable to a counterparty that declines to fetch — wherever Bazaar
+ * governs, it is rejected outright. LCP v1.38 §C.4 draws the same conclusion ("publish a resolvable
+ * schema or inline it — and inlining is the safer of the two"). Dropping `$id` and `$defs` from the
+ * inlined form is that rule applied: the authority document's `$id` is an absolute URL, and its `$defs`
+ * carries the RECEIPT-time definition, which is not this challenge-time `info` and would bloat every 402.
  *
- * **Both extensions published in the x402 repository inline a complete JSON Schema** rather than
- * referencing an external document, and LCP v1.38 §C.4 says to do one or the other: "Because `schema` is a
- * REQUIRED member, publish a resolvable schema or inline it." Inlining also removes a hosting dependency
- * the deployment does not currently meet — the same dependency the UCP capability still owes.
- *
- * The shape is the §8.1 reference object this placement writes into `info`, and nothing more: it describes
- * the carrier, not the terms behind it.
+ * The shape is the §8.1 reference object PLUS the locator the reference is verified through:
+ * `legalContextUrl` is REQUIRED here because `value` is a digest — a buyer verifies the terms by fetching
+ * the document and hashing it, so a challenge advertising the hash without the locator advertises
+ * something no counterparty who lacks the document can check. Every shipped buyer parser already refuses
+ * such a challenge; the schema now says on the wire what the readers always demanded. It describes the
+ * carrier, not the terms behind it, and asserts nothing about any agreement's lawfulness — the
+ * description says so in as many words because the schema travels alone.
  *
  * Changing this is a WIRE change — it appears in every challenge — so it is a frozen literal rather than a
- * value assembled at call time.
+ * value assembled at call time, and the drift gate is what keeps the frozen copy honest.
  */
 export const LEGAL_CONTEXT_SCHEMA: Readonly<Record<string, unknown>> =
   Object.freeze({
     $schema: "https://json-schema.org/draft/2020-12/schema",
-    title: "LCP legal-context reference",
+    title: "legalContext — x402 extension info",
     description:
-      "A Legal Context Protocol reference to the terms governing this transaction. The reference identifies the exact terms document; it is not the terms.",
+      "The `info` payload of the `legalContext` x402 extension at challenge time: a Legal Context Protocol reference to the terms governing this transaction, plus the URL the terms document can be fetched from. The reference identifies the exact terms document; it is not the terms. This describes a technology harness and asserts nothing about whether any agreement is lawful, sound or enforceable.",
     type: "object",
-    required: ["type", "value"],
     additionalProperties: false,
+    required: ["type", "value", "legalContextUrl"],
     properties: {
       type: {
-        type: "string",
-        enum: ["sha256", "url", "ipfs", "ar"],
         description:
-          "Carrier type. sha256, ipfs and ar are content-addressed and bear integrity; url only locates a document.",
+          "The digest algorithm over the terms document. `sha256` is the only value this version defines.",
+        type: "string",
+        const: "sha256",
       },
       value: {
+        description:
+          "The atrHash — SHA-256 of the terms document, lowercase hex with an 0x prefix.",
         type: "string",
-        minLength: 1,
+        pattern: "^0x[0-9a-f]{64}$",
+      },
+      legalContextUrl: {
         description:
-          "The reference itself — for sha256, a 0x-prefixed lowercase 32-byte hex digest of the complete ATR file.",
+          "Where the terms document this hash covers can be fetched. A reader verifies the document against `value`; the URL is a locator and never the authority.",
+        type: "string",
+        format: "uri",
       },
     },
   });
 
 /**
  * x402 reference placement — the HTTP-layer carrier, cut against the live x402 v2 specification
- * (`x402-foundation/x402@1fec3aa04e41`, `specs/x402-specification-v2.md`; gate discharged in the README).
+ * (`x402-foundation/x402@db5da2e65952`, `specs/x402-specification-v2.md`, read 2026-08-11; gate discharged
+ * in the README).
  *
  * **THE CANONICAL REPOSITORY IS THE FOUNDATION'S, and the citation moved on 2026-08-08.** Every
  * reference here named `coinbase/x402`, which the GitHub API reports as `"fork": true`;
@@ -90,39 +112,47 @@ export const LEGAL_CONTEXT_SCHEMA: Readonly<Record<string, unknown>> =
  * would emit something no x402 counterparty parses. This is the reason an alias declares its own `encoding`
  * at all.
  *
- * **The alias declares no `write`, and the live spec is the reason.** `extra` is "Scheme-specific additional
- * information" — the payment scheme's object, whose contents that scheme defines. An `atrHash` is READ there
- * because sellers put one there; writing into another party's namespace is not the same act. The
- * `extensions` map is the protocol's own declared extension point and is where `place` writes.
+ * **The alias IS WRITTEN, and this reverses a recorded stance — deliberately, on three grounds.** The
+ * predecessor declared no `write` on the reasoning that `extra` is "Scheme-specific additional information"
+ * and writing into another party's namespace is not our act. That reasoning has been overtaken. First, the
+ * host itself no longer treats `extra` as wholly scheme-private: §6.1 reserves `assetTransferMethod` and
+ * `paymentFlow` inside it as protocol-governed names, so `extra` is a host-managed extension surface with
+ * scheme-specific residue, not a foreign namespace. Second, LCP v1.38 §C.4's own Tier A illustration puts
+ * `atrHash` AND `legalContextUrl` in `accepts[].extra` — a third-party reader built from the spec's example
+ * reads `extra` first, and a challenge that leaves it empty is invisible to that reader. Third, the shipped
+ * buyer parser reads BOTH carriers and reconciles, refusing disagreement — so the mirror cannot drift
+ * silently: two slots either agree or the document refuses at the counterparty. The write lands only in
+ * `accepts[0]`, the requirement buyer parsers read (see the index-0 rule below), and never touches the
+ * reserved names.
  *
  * **The alias is index 0 only.** A locator names one path. `accepts[0]` is what buyer parsers read, and the
  * reason is substantive: the reference must bind to the requirement actually being paid, and searching every
  * requirement would let a seller park a second set of terms on an alternative it never expects to be chosen.
  *
- * **`termsUrlField` is DECLARED — this is the protocol whose wire carries both halves.** `binding-core`'s own
- * contract cites x402 for exactly that: a buyer-side parser may demand the URL because x402 carries it, and
- * emitters put `legalContextUrl` inside `info` beside `type`/`value`. Declaring the path
- * makes that half machine-readable instead of a second private convention; `place` never writes it, because
- * `place(ref, doc)` holds one reference and the terms URL is a different datum (the same division ACP draws
- * with `metadata.legal_context_url`). The shipped carrier repeats the URL at `accepts[0].extra.legalContextUrl`
- * too, which a single `termsUrlField` cannot express — recorded in the README as a known limitation rather
- * than half-declared here.
+ * **`termsUrlFields` declares BOTH slots the wire carries, and both are written.** The predecessor member
+ * (`termsUrlField`, singular) named only the `extensions` slot, and it was read-only in every published
+ * package — the write path did not exist anywhere, so a seller assembling from published parts emitted a
+ * challenge advertising a hash with no locator, which the published buyer refuses
+ * (integra-protocol#8). Declaring both slots makes the manifest state what actually lands on the wire:
+ * `place` writes the URL beside the reference in `info` (where the authority schema requires it) and
+ * mirrors it at `accepts[0].extra.legalContextUrl` (where §C.4's illustration carries it), and `extract`
+ * reconciles the two, refusing disagreement. The kit REQUIRES the URL of any integrity-bearing
+ * advertisement on this manifest — a hash no counterparty can resolve is unverifiable by construction,
+ * which is the defect the readers always guarded against and the emitters never did.
  *
- * **`carrierTypes` permits `sha256` and `url`, and the two are admitted on DIFFERENT grounds** — one reason
- * cannot cover both. `sha256` is the integrity carrier: §C.4's illustration carries one, emitters carry one,
- * and the bare alias is fixed to it. `url` is the §8.1 discovery form, admitted because the canonical
- * slot is a general reference-object slot and the kit puts the integrity-versus-discovery decision at the
- * READER — `carrierClass` plus `requireIntegrity` — not in the permission list; ACP and UCP permit it for the
- * same reason. `ipfs`/`ar` are excluded on a ground that does NOT apply to `url`: they are ALTERNATIVE
- * integrity carriers, so admitting one adds no capability `sha256` does not already discharge while
- * advertising a content-addressed transport no x402 counterparty resolves — a claim about the ecosystem
- * rather than a description of it.
- *
- * The `url` permission is nonetheless WIDER than any shipped x402 reader: a buyer parser that requires an
- * integrity carrier refuses `info.type !== "sha256"` outright, so a `url` placed in this slot is well-formed
- * against this manifest and would still be rejected at read time. Recorded in the README as a limitation
- * rather than narrowed away here, because narrowing the reference field to one type is a change to what the
- * SLOT may hold across the set, not a fact about x402.
+ * **`carrierTypes` is `sha256` alone, and the `url` admission is WITHDRAWN — a defect resolved, not a
+ * preference.** The predecessor admitted `url` as the §8.1 discovery form and recorded, in the same
+ * docblock, that the permission was "WIDER than any shipped x402 reader": a buyer parser that requires an
+ * integrity carrier refuses `info.type !== "sha256"` outright, so a `url` placed in this slot was
+ * well-formed against the manifest and rejected at read time — a permission no reader accepts, which is a
+ * claim about the ecosystem rather than a description of it. The withdrawal ground is now structural: the
+ * `schema` member this package puts on the wire is the AUTHORITY document's shape, whose `type` is
+ * `const: "sha256"`, so a `url` reference would emit a challenge that violates its own adjacent schema.
+ * The predecessor declined to narrow because "narrowing the reference field to one type is a change to
+ * what the SLOT may hold across the set" — that set-wide decision has since been made, by the authority
+ * document. `ipfs`/`ar` remain excluded on the original ground: alternative integrity carriers add no
+ * capability `sha256` does not already discharge while advertising a content-addressed transport no x402
+ * counterparty resolves.
  */
 export const X402_PLACEMENT: PlacementManifest = {
   protocol: "x402",
@@ -136,10 +166,14 @@ export const X402_PLACEMENT: PlacementManifest = {
       path: "accepts.0.extra.atrHash",
       encoding: "bare-value",
       bareType: "sha256",
+      write: true,
     },
   ],
-  termsUrlField: "extensions.legalContext.info.legalContextUrl",
-  carrierTypes: ["sha256", "url"],
+  termsUrlFields: [
+    "extensions.legalContext.info.legalContextUrl",
+    "accepts.0.extra.legalContextUrl",
+  ],
+  carrierTypes: ["sha256"],
   specRef:
-    "x402 v2 (x402-foundation/x402@1fec3aa04e41 specs/x402-specification-v2.md, read 2026-07-30) — top-level extensions map carried on PaymentRequired/PaymentPayload/SettlementResponse, each entry {info, schema}; accepts[].extra is scheme-specific (gate discharged: see README)",
+    "x402 v2 (x402-foundation/x402@db5da2e65952 specs/x402-specification-v2.md, read 2026-08-11) — top-level extensions map carried on PaymentRequired/PaymentPayload/SettlementResponse, each entry {info, schema}; accepts[].extra carries the §C.4 mirror (reserved names per §6.1 untouched; gate discharged: see README)",
 };

package/src/placement.ts

@@ -1,116 +1,68 @@
 import {
-  CarrierError,
-  encodeForField,
-  type LegalContextRef,
+  type LegalContextAdvertisement,
   makePlacement,
   type Outcome,
   type ReferencePlacementAdapter,
+  readAtPath,
+  requireWritten,
+  writeToContainer,
 } from "@integraledger/lcp-binding-core";
 import { LEGAL_CONTEXT_SCHEMA, X402_PLACEMENT } from "./manifest.js";
 
 const base = makePlacement(X402_PLACEMENT);
 
-/** Refusals namespaced from the protocol id, exactly as the kit does — so `x402/document-malformed` means the
- *  same thing whether it came from the override or from the generic read path. */
-function refuse(code: string, detail: string): Outcome<never> {
-  return {
-    refused: true,
-    haltClass: "verification-failure",
-    code: `x402/${code}`,
-    detail,
-  };
-}
-
 /**
- * The x402 reference placement — the kit's `extract`, and the ONE `place` in the set that the kit cannot
- * supply.
+ * The x402 reference placement — the kit, plus the ONE wrapper the kit cannot know.
+ *
+ * x402's slot does not hold the reference directly: it holds `{ info, schema }`, where `info` is the
+ * carrier payload and `schema` is the inlined JSON Schema describing it (a REQUIRED member per x402
+ * §5.1.2). That wrapper is a protocol fact no container kind models, so `place` is overridden — but as
+ * COMPOSITION over `base.place`, not as a reimplementation beside it. The kit performs the entire
+ * placement first: the advertisement rules (terms URL demanded of an integrity-bearing reference,
+ * refused where malformed), the canonical write into `extensions.legalContext.info`, the bare-hash
+ * mirror into `accepts[0].extra.atrHash`, the terms-URL writes into BOTH declared slots, every
+ * malformed-container refusal, and purity. The override then does exactly one thing: rebuilds our entry
+ * as `{ info, schema }` so the wrapper's second member lands beside the payload the kit just wrote.
  *
- * x402's slot does not hold the reference directly: it holds `{ info, schema }`, where `info` is the §8.1
- * reference object and `schema` is a `$ref` pointing at the carrier schema. That is a WRAPPER, and no
- * container kind models it. Inventing an `x402-extension` container kind would put one protocol's name inside
- * a generic enum — the abstraction leaking — so the write half is overridden here, in this package, where it
- * is reviewed like any other code. `extract` is the kit's unchanged: reading `extensions.legalContext.info` is
- * an ordinary object-path read, and the bare-hash alias at `accepts.0.extra.atrHash` is handled by its own
- * declared encoding (S2/S6). One overridden member is composition; a second would mean this package had
- * stopped using the kit, and the test suite says so.
+ * The predecessor override reimplemented the write wholesale — sibling preservation, own-property
+ * walks, the malformed-`extensions` refusal, all restated beside the kit's copies — which is how it
+ * could drift: it froze a schema and never wrote a terms URL while the kit's manifest declared one
+ * (integra-protocol#8). A one-member rebuild has no room to disagree with the manifest, because
+ * everything the manifest declares is discharged before it runs.
+ *
+ * Rebuilding the ENTRY wholesale (rather than merging `schema` into whatever sits there) is the
+ * predecessor's ratified behaviour, kept: our entry is the direct holder and is REPLACED, so junk a
+ * counterparty parked inside `extensions.legalContext` does not ride our wire; sibling entries in
+ * `extensions` survive untouched, per the host's own echo rule. `extract` is the kit's, unchanged —
+ * reading `info` is an ordinary object-path read, the alias and both terms-URL slots are declared data,
+ * and reconciliation lives where every protocol shares it.
  */
 export const x402Placement: ReferencePlacementAdapter = {
   ...base,
 
-  place(ref: LegalContextRef, doc: unknown): Outcome<unknown> {
-    if (!X402_PLACEMENT.carrierTypes.includes(ref.type))
-      return refuse(
-        "carrier-type-not-permitted",
-        `${X402_PLACEMENT.field} permits ${X402_PLACEMENT.carrierTypes.join("/")}, got ${ref.type}`,
-      );
-    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
-      return refuse(
-        "document-malformed",
-        "an x402 challenge is a non-null object",
-      );
-
-    // Rendered through the codec, never by interpolation — a value that does not meet its type's rule refuses
-    // here instead of putting an extension on the wire that a buyer's parser would reject.
-    let encoded: unknown;
-    try {
-      encoded = encodeForField(ref, X402_PLACEMENT.encoding);
-    } catch (e) {
-      if (!(e instanceof CarrierError)) throw e; // never swallow a non-carrier bug
-      return refuse(
-        "reference-malformed",
-        `not a valid carrier value for its type: ${ref.value}`,
-      );
-    }
-
-    // OWN PROPERTY ONLY. `place`'s document is exactly as attacker-influenced as `extract`'s, so a challenge
-    // with ZERO own properties must not walk into its prototype's `extensions` and put those entries on the
-    // wire — `extract` reports that document as `reference-absent`, and the two halves have to agree about
-    // what is present. binding-core's own writer states the rule and proves it for the generic path; the
-    // override is the one write path that has to restate it. The DECLARED view rather than a
-    // `Record<string, unknown>` is deliberate: reading `extensions` off an index signature is TS4111, and the
-    // bracket form biome would then ask for is the fix it classes as unsafe. The document is still spread
-    // wholesale below, so nothing is narrowed away.
-    const ext = Object.hasOwn(doc, "extensions")
-      ? (doc as { readonly extensions?: unknown }).extensions
-      : undefined;
-
-    // Sibling extensions are PRESERVED: the live x402 v2 spec states a client "must include at least the info
-    // received; it may append additional info but cannot delete or overwrite existing info". That is the host
-    // protocol's rule about its own map, and a placement that pruned a sibling would make the client
-    // using it non-conformant.
-    //
-    // An `extensions` that is PRESENT but cannot be merged into REFUSES, and that is binding-core's ratified
-    // malformed-container rule read against the manifest this package PUBLISHES rather than against the
-    // granularity the override happens to write at: `field` is `extensions.legalContext.info`, so `legalContext`
-    // is the field's direct holder and `extensions` sits one level ABOVE it — replaced at the holder, refused
-    // above it, because replacing an intermediate discards everything beneath it. A stranger holding only the
-    // manifest and the kit computes that refusal for the same document, and an override that emitted a
-    // challenge instead would make the manifest a description rather than an artifact. ABSENT is still
-    // created; our own entry, being the direct holder, is still replaced.
-    const siblings =
-      ext === undefined
-        ? {}
-        : typeof ext === "object" && ext !== null && !Array.isArray(ext)
-          ? (ext as Record<string, unknown>)
-          : undefined;
-    if (siblings === undefined)
-      return refuse(
-        "document-malformed",
-        `extensions is present and is not a map, so ${X402_PLACEMENT.field} has no holder to write into: ${JSON.stringify(ext)}`,
-      );
-
-    return {
-      ok: true,
-      value: {
-        ...(doc as object),
-        extensions: {
-          ...siblings,
-          legalContext: {
-            info: encoded,
-            schema: LEGAL_CONTEXT_SCHEMA,
-          },
+  place(ad: LegalContextAdvertisement, doc: unknown): Outcome<unknown> {
+    const placed = base.place(ad, doc);
+    if ("refused" in placed) return placed;
+    // The kit's write just created this path on its own output; reading it back — rather than re-encoding
+    // the reference a second time — keeps one codepath responsible for what `info` contains.
+    const info = readAtPath(placed.value, X402_PLACEMENT.field);
+    // TOTAL by the kit's own postconditions: `place` succeeded, so `placed.value` is a record; the write's
+    // parent path is the one-segment `extensions`, and a direct holder that is present-but-unmergeable is
+    // REPLACED under the ratified container rule, never refused. `requireWritten` states that rather than
+    // asserting it with a cast — if the postcondition ever breaks, this throws instead of returning a
+    // success carrying no document.
+    const wrapped = requireWritten(
+      writeToContainer(
+        placed.value,
+        X402_PLACEMENT.container,
+        "extensions.legalContext",
+        {
+          info,
+          schema: LEGAL_CONTEXT_SCHEMA,
         },
-      },
-    };
+      ),
+      "x402Placement.place",
+    );
+    return { ok: true, value: wrapped };
   },
 };