@integraledger/lcp-placement-ucp 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # @integraledger/lcp-placement-ucp
 
+## 0.12.0
+
+### Patch Changes
+
+- @integraledger/lcp-binding-core@0.12.0
+
+## 0.11.0
+
+### Minor Changes
+
+- b2ffecc: Report the class a record actually supports, place a terms URL on UCP, and stop refusing a conformant UCP
+  profile — the remediation of the 2026-08-19 conformance re-audit.
+
+  **`verify` now computes `supportedClass` instead of echoing the claim.** It was `anyFailed ? "TC-0" :
+claimedClass`, so a record proving nothing — no settlement, no acceptance, no authority chain — reported
+  whatever class the caller named, while the field's own published docblock promised "what the record
+  honestly supports, not what the caller asked for". It is now the highest class every one of whose required
+  steps is `proved`, `TC-0` on any failure, computed from the steps alone: neither capped by the claim (rungs
+  that reach TC-3 read TC-3 where the caller claimed TC-2) nor lifted by it. White paper #4 §5 defines the
+  class of a transaction as "the highest class whose criteria it fully meets", and this is that.
+
+  The claim is not discarded — the report gains **`claimedClass`**, a required member, because `verified`
+  answers "did the record reach the class it claimed?" and cannot be read without it. The two fields are the
+  report's two halves: an input echoed, and a finding computed. Where they differ, the record did not reach
+  its own shape. An out-of-taxonomy claim now lands only in the echo and can no longer masquerade as a
+  finding.
+
+  **UCP can advertise a terms URL.** Its policy object declares `url` — "Optional link to the full policy
+  document", `format: uri` — on the very entry this placement writes, and §C.3's illustration carries `url`
+  and `atrHash` side by side there. The manifest previously said the protocol had no slot, citing `links[]`,
+  which §C.3 separates as "a standing page, not a per-transaction record". The obstacle was mechanical:
+  `termsUrlFields` addresses document paths, and a tagged-array entry's index is chosen at write time. The
+  `tagged-array` container therefore gains `termsUrlField`, written onto the same entry in the same write, and
+  read back through the same first-match rule. UCP was the last shipped protocol that refused an
+  advertisement carrying its own locator (integra-protocol#8).
+
+  **`readUcpProfile` no longer refuses a conformant business profile.** `requireHttps` mapped an ABSENT `spec`
+  to the same branch as a malformed one, and the live host requires `spec` only of a platform declaration —
+  as this repository's own README already said. It is now `requireHttpsIfDeclared`: absence is absence, and a
+  declared value is still held to the host's https MUST.
+
+  Also: `requireWritten` replaces an unchecked cast in the x402 override, so a broken postcondition throws
+  instead of returning a success carrying no document; six x402 citations move to the revision that actually
+  touches the file they name, and a new gate refuses any `owner/repo@sha` in source that `spec-pins.json` does
+  not record; four spec citations move from line anchors to section anchors; the escrow binding states why it
+  declares no §8.3.1 off-canonical variant, and asserts it; and §C.3's `policies[]` illustration is recorded as
+  invalid against the live UCP schema, which shows `description` as a bare string where the host requires an
+  object — owed upstream, not a defect here.
+
+  Corpus 844 → 847, root `ec4ad1b02a81538b…`.
+
+- 822190a: Give the terms URL the write path the published set never had, and certify the composition that broke
+  without it (integra-protocol#8).
+
+  A third party assembling a seller from published parts emitted a 402 the published buyer refuses: every
+  published reader demanded `legalContextUrl` and no published writer placed it, and the schema
+  `placement-x402` inlined onto the wire (`required: ["type","value"]`, closed) contradicted the authority
+  document integraledger.com serves (`required: ["type","value","legalContextUrl"]`, closed) — two
+  definitions of one `info`, no document valid against both, each package self-consistent. Three structural
+  gaps let it ship: the manifest's `termsUrlField` was singular and read-only (declared, hygiene-checked,
+  never written — and x402's wire carries the URL in two slots, so one path could not even name the shape),
+  nothing compared the inlined schema to the authority document, and the corpus certified `place` and
+  `extract` separately but never fed one to the other.
+
+  `binding-core` — the placement seam now moves an ADVERTISEMENT, not a bare reference. `place` takes
+  `{ ref, termsUrl? }` and writes the URL at every slot the manifest's new `termsUrlFields` (plural,
+  replacing `termsUrlField`) declares; it REFUSES an integrity-bearing advertisement with no URL where slots
+  are declared (a hash no counterparty can resolve is unverifiable by construction), a URL where no slot
+  exists (silent dropping is fail-open), and a non-https URL on either side of the seam. `extract` returns
+  `{ ref, termsUrl }` with absence as a typed value — `no-field-declared` is a fact about the protocol,
+  `declared-fields-empty` a fact about the document, and the gate decides what an absence means — while two
+  slots that disagree, or a malformed value in either, refuse. The object-path writer learned to descend
+  into an EXISTING array element (never minting one, never extending a list, refusing an index segment it
+  would have to create), which is what lets x402's `accepts[0].extra` mirrors land.
+
+  `placement-x402` — the inlined wire schema now IS the authority document minus `$id` and `$defs`
+  (Bazaar forbids both on the wire), drift-gated in `lcp-conformance` where the two packages meet.
+  `termsUrlFields` declares both slots the wire carries; the bare-hash alias is written (`extra` stopped
+  being wholly scheme-private when x402 §6.1 reserved names inside it, and LCP v1.38 §C.4's own Tier A
+  illustration carries the pair there); the `url` carrier admission is withdrawn (`carrierTypes` is
+  `sha256` alone — the schema on the wire is `const: "sha256"`, and no shipped reader ever accepted a url
+  in this slot). The `place` override shrinks to composition: the kit performs the whole placement and the
+  override adds only the `{info, schema}` wrapper.
+
+  `placement-mpp` / `placement-acp` — the singular member becomes the one-entry `termsUrlFields`; the kit
+  now writes the slot their buyer parsers always demanded and refuses first at the seller.
+
+  `lcp-conformance` — the corpus grows 812 → 844: a `roundtrip` op (place then extract in one case, the
+  composition certification whose absence let two separately-conformant halves ship jointly broken),
+  advertisement-rule refusals for every manifest, and the authority↔wire drift gate. Extract expectations
+  across every placement area become the extracted advertisement.
+
+  `lcp-verify` — `referencePlacementStep` reads the advertisement (`extracted.ref.value`) and deliberately
+  ignores `termsUrl`: where the terms live is the gate's fetch concern, not a fact the record can
+  contradict.
+
+  `lcp-discovery` — the x402 authority document restates the atrHash pattern inline in both definitions
+  (no `$defs` indirection the wire copy would have to rewrite) and moves the two-definitions rationale into
+  `$defs.receipt`, so the challenge-time root is byte-derivable for the wire.
+
+### Patch Changes
+
+- Updated dependencies [b2ffecc]
+- Updated dependencies [822190a]
+  - @integraledger/lcp-binding-core@0.11.0
+
 ## 0.10.1
 
 **0.10.0 was staged and withdrawn before approval; this is that release, re-cut.** The conformance corpus

package/README.md

@@ -37,7 +37,7 @@ import { UCP_PLACEMENT, ucpPlacement } from "@integraledger/lcp-placement-ucp";
 
 declare const checkout: unknown; // the UCP checkout response, as received
 
-const placed = ucpPlacement.place({ type: "sha256", value: "0x…" }, checkout);
+const placed = ucpPlacement.place({ ref: { type: "sha256", value: "0x…" } }, checkout);
 const ref = ucpPlacement.extract(checkout);
 ```
 
@@ -108,7 +108,7 @@ alone. Both arms are pinned as vectors.
 
 ## Why the links alias has no `write` flag
 
-The links entry carries the terms **URL** — a different datum than the atrHash — and `place(ref, doc)`
+The links entry carries the terms **URL** — a different datum than the atrHash — and `place(ad, doc)`
 holds one reference, not two data: writing `ref.value` into `links[].url` would put a bare hash where every
 UCP client expects a URL. Publishing the links entry is the deployment's act (UCP already makes `links[]`
 required on checkout responses), and this placement **reads** it: `extract` falls to the alias when no policy entry is

package/dist/manifest.d.ts

@@ -66,12 +66,18 @@ import type { PlacementManifest } from "@integraledger/lcp-binding-core";
  * `links[].type` is an OPEN set ("Businesses MAY define custom types"); the well-known `terms_of_service`
  * tag is used because it is the spelling counterparties already read, not because it is the only one legal.
  *
- * **`termsUrlField` is deliberately OMITTED.** The terms URL rides `links[type=terms_of_service].url` — a
- * tagged-array locator that a dotted-path parser cannot resolve. Declaring it as `termsUrlField` would
- * repeat the defect the `field` rule exists to prevent: a declared property that is not the declared thing.
- * The discovery
- * alias states the same fact WITH its machine-readable container, and the `PlacementManifest` contract says
- * an absent `termsUrlField` means a parser must not demand one.
+ * **The terms URL rides the policies entry, declared as the container's `termsUrlField`.** UCP's policy
+ * object is `additionalProperties: true` and declares `url` outright — "Optional link to the full policy
+ * document", `format: uri` (re-verified at UCP HEAD, `source/schemas/shopping/types/policy.json`) — and
+ * §C.3's own illustration carries `url` and `atrHash` side by side in ONE entry. So the per-transaction
+ * locator belongs on the per-transaction record, which is the entry this placement writes.
+ *
+ * It is declared container-relative rather than in `termsUrlFields` because the entry's index is chosen at
+ * write time (replace-by-tag, else append), so no dotted path names it — not because the host lacks a slot.
+ * `links[]` is NOT that slot and never was: §C.3 separates the two explicitly, `links[]` being "a standing
+ * page, not a per-transaction record". A predecessor of this manifest gave the links entry as the reason
+ * this placement could advertise no terms URL at all, which read the wrong carrier and left UCP the one
+ * shipped protocol that refused an advertisement carrying its locator (integra-protocol#8).
  *
  * **`carrierTypes` permits `sha256` and `url`, and `url` is load-bearing.** extract checks every decoded
  * reference against this list, so the discovery alias's url-typed hits would refuse

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,eAAO,MAAM,aAAa,EAAE,iBAyC3B,CAAC"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,eAAO,MAAM,aAAa,EAAE,iBA6C3B,CAAC"}

package/dist/manifest.js

@@ -65,12 +65,18 @@
  * `links[].type` is an OPEN set ("Businesses MAY define custom types"); the well-known `terms_of_service`
  * tag is used because it is the spelling counterparties already read, not because it is the only one legal.
  *
- * **`termsUrlField` is deliberately OMITTED.** The terms URL rides `links[type=terms_of_service].url` — a
- * tagged-array locator that a dotted-path parser cannot resolve. Declaring it as `termsUrlField` would
- * repeat the defect the `field` rule exists to prevent: a declared property that is not the declared thing.
- * The discovery
- * alias states the same fact WITH its machine-readable container, and the `PlacementManifest` contract says
- * an absent `termsUrlField` means a parser must not demand one.
+ * **The terms URL rides the policies entry, declared as the container's `termsUrlField`.** UCP's policy
+ * object is `additionalProperties: true` and declares `url` outright — "Optional link to the full policy
+ * document", `format: uri` (re-verified at UCP HEAD, `source/schemas/shopping/types/policy.json`) — and
+ * §C.3's own illustration carries `url` and `atrHash` side by side in ONE entry. So the per-transaction
+ * locator belongs on the per-transaction record, which is the entry this placement writes.
+ *
+ * It is declared container-relative rather than in `termsUrlFields` because the entry's index is chosen at
+ * write time (replace-by-tag, else append), so no dotted path names it — not because the host lacks a slot.
+ * `links[]` is NOT that slot and never was: §C.3 separates the two explicitly, `links[]` being "a standing
+ * page, not a per-transaction record". A predecessor of this manifest gave the links entry as the reason
+ * this placement could advertise no terms URL at all, which read the wrong carrier and left UCP the one
+ * shipped protocol that refused an advertisement carrying its locator (integra-protocol#8).
  *
  * **`carrierTypes` permits `sha256` and `url`, and `url` is load-bearing.** extract checks every decoded
  * reference against this list, so the discovery alias's url-typed hits would refuse
@@ -104,6 +110,10 @@ export const UCP_PLACEMENT = {
                 plain: "Terms of sale for this order, identified by a Legal Context Protocol reference. The reference identifies the exact terms document; it is not itself the terms.",
             },
         },
+        // `url` is declared on this very object by the host — "Optional link to the full policy document",
+        // format uri — and §C.3's illustration carries it beside `atrHash` in one entry. Verified at UCP HEAD
+        // (source/schemas/shopping/types/policy.json).
+        termsUrlField: "url",
     },
     field: "policies[type=com.integraledger.policy.legal_context]",
     readAlso: [

package/dist/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC9C,QAAQ,EAAE,KAAK;IACf,OAAO,EAAE,eAAe;IACxB,IAAI,EAAE,GAAG;IACT,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE;QACT,IAAI,EAAE,cAAc;QACpB,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,MAAM;QAChB,GAAG,EAAE,wCAAwC;QAC7C,UAAU,EAAE,iCAAiC;QAC7C,mGAAmG;QACnG,iGAAiG;QACjG,yGAAyG;QACzG,uCAAuC;QACvC,SAAS,EAAE;YACT,WAAW,EAAE;gBACX,KAAK,EACH,gKAAgK;aACnK;SACF;KACF;IACD,KAAK,EAAE,uDAAuD;IAC9D,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,kCAAkC;YACxC,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,WAAW;YACzB,SAAS,EAAE;gBACT,IAAI,EAAE,cAAc;gBACpB,EAAE,EAAE,OAAO;gBACX,QAAQ,EAAE,MAAM;gBAChB,GAAG,EAAE,kBAAkB;gBACvB,UAAU,EAAE,KAAK;aAClB;SACF;KACF;IACD,YAAY,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;IAC/B,OAAO,EACL,sWAAsW;CACzW,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC9C,QAAQ,EAAE,KAAK;IACf,OAAO,EAAE,eAAe;IACxB,IAAI,EAAE,GAAG;IACT,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE;QACT,IAAI,EAAE,cAAc;QACpB,EAAE,EAAE,UAAU;QACd,QAAQ,EAAE,MAAM;QAChB,GAAG,EAAE,wCAAwC;QAC7C,UAAU,EAAE,iCAAiC;QAC7C,mGAAmG;QACnG,iGAAiG;QACjG,yGAAyG;QACzG,uCAAuC;QACvC,SAAS,EAAE;YACT,WAAW,EAAE;gBACX,KAAK,EACH,gKAAgK;aACnK;SACF;QACD,mGAAmG;QACnG,sGAAsG;QACtG,+CAA+C;QAC/C,aAAa,EAAE,KAAK;KACrB;IACD,KAAK,EAAE,uDAAuD;IAC9D,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,kCAAkC;YACxC,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,WAAW;YACzB,SAAS,EAAE;gBACT,IAAI,EAAE,cAAc;gBACpB,EAAE,EAAE,OAAO;gBACX,QAAQ,EAAE,MAAM;gBAChB,GAAG,EAAE,kBAAkB;gBACvB,UAAU,EAAE,KAAK;aAClB;SACF;KACF;IACD,YAAY,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;IAC/B,OAAO,EACL,sWAAsW;CACzW,CAAC"}

package/dist/placement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,iCAAiC,CAAC;AAKzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,EAAE,yBAc1B,CAAC"}
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,iCAAiC,CAAC;AAKzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,EAAE,yBAe1B,CAAC"}

package/dist/placement.js

@@ -30,12 +30,13 @@ export const ucpPlacement = {
         const out = base.extract(doc);
         if ("refused" in out)
             return out;
-        if (out.value.type === "url" && !out.value.value.startsWith("https://"))
+        const { ref } = out.value;
+        if (ref.type === "url" && !ref.value.startsWith("https://"))
             return {
                 refused: true,
                 haltClass: "verification-failure",
                 code: "ucp/insecure-terms-url",
-                detail: `a terms link must be HTTPS — an http: reference is rewritable in transit: ${out.value.value}`,
+                detail: `a terms link must be HTTPS — an http: reference is rewritable in transit: ${ref.value}`,
             };
         return out;
     },

package/dist/placement.js.map

@@ -1 +1 @@
-{"version":3,"file":"placement.js","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,GAEd,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,IAAI,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,YAAY,GAA8B;IACrD,GAAG,IAAI;IACP,OAAO,CAAC,GAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,SAAS,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;QACjC,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC;YACrE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,sBAAsB;gBACjC,IAAI,EAAE,wBAAwB;gBAC9B,MAAM,EAAE,6EAA6E,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE;aACvG,CAAC;QACJ,OAAO,GAAG,CAAC;IACb,CAAC;CACF,CAAC"}
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,GAEd,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,IAAI,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,YAAY,GAA8B;IACrD,GAAG,IAAI;IACP,OAAO,CAAC,GAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,SAAS,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;QACjC,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC;QAC1B,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC;YACzD,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,sBAAsB;gBACjC,IAAI,EAAE,wBAAwB;gBAC9B,MAAM,EAAE,6EAA6E,GAAG,CAAC,KAAK,EAAE;aACjG,CAAC;QACJ,OAAO,GAAG,CAAC;IACb,CAAC;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integraledger/lcp-placement-ucp",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Places an LCP reference into a UCP (Universal Commerce Protocol) checkout, and reads it back.",
   "keywords": [
     "lcp",
@@ -40,7 +40,7 @@
   },
   "homepage": "https://github.com/IntegraLedger/integra-protocol/tree/main/packages/placement-ucp#readme",
   "dependencies": {
-    "@integraledger/lcp-binding-core": "0.10.1"
+    "@integraledger/lcp-binding-core": "0.12.0"
   },
   "devDependencies": {
     "@cfworker/json-schema": "4.1.1",

package/src/manifest.ts

@@ -67,12 +67,18 @@ import type { PlacementManifest } from "@integraledger/lcp-binding-core";
  * `links[].type` is an OPEN set ("Businesses MAY define custom types"); the well-known `terms_of_service`
  * tag is used because it is the spelling counterparties already read, not because it is the only one legal.
  *
- * **`termsUrlField` is deliberately OMITTED.** The terms URL rides `links[type=terms_of_service].url` — a
- * tagged-array locator that a dotted-path parser cannot resolve. Declaring it as `termsUrlField` would
- * repeat the defect the `field` rule exists to prevent: a declared property that is not the declared thing.
- * The discovery
- * alias states the same fact WITH its machine-readable container, and the `PlacementManifest` contract says
- * an absent `termsUrlField` means a parser must not demand one.
+ * **The terms URL rides the policies entry, declared as the container's `termsUrlField`.** UCP's policy
+ * object is `additionalProperties: true` and declares `url` outright — "Optional link to the full policy
+ * document", `format: uri` (re-verified at UCP HEAD, `source/schemas/shopping/types/policy.json`) — and
+ * §C.3's own illustration carries `url` and `atrHash` side by side in ONE entry. So the per-transaction
+ * locator belongs on the per-transaction record, which is the entry this placement writes.
+ *
+ * It is declared container-relative rather than in `termsUrlFields` because the entry's index is chosen at
+ * write time (replace-by-tag, else append), so no dotted path names it — not because the host lacks a slot.
+ * `links[]` is NOT that slot and never was: §C.3 separates the two explicitly, `links[]` being "a standing
+ * page, not a per-transaction record". A predecessor of this manifest gave the links entry as the reason
+ * this placement could advertise no terms URL at all, which read the wrong carrier and left UCP the one
+ * shipped protocol that refused an advertisement carrying its locator (integra-protocol#8).
  *
  * **`carrierTypes` permits `sha256` and `url`, and `url` is load-bearing.** extract checks every decoded
  * reference against this list, so the discovery alias's url-typed hits would refuse
@@ -107,6 +113,10 @@ export const UCP_PLACEMENT: PlacementManifest = {
           "Terms of sale for this order, identified by a Legal Context Protocol reference. The reference identifies the exact terms document; it is not itself the terms.",
       },
     },
+    // `url` is declared on this very object by the host — "Optional link to the full policy document",
+    // format uri — and §C.3's illustration carries it beside `atrHash` in one entry. Verified at UCP HEAD
+    // (source/schemas/shopping/types/policy.json).
+    termsUrlField: "url",
   },
   field: "policies[type=com.integraledger.policy.legal_context]",
   readAlso: [

package/src/placement.ts

@@ -34,12 +34,13 @@ export const ucpPlacement: ReferencePlacementAdapter = {
   extract(doc: unknown) {
     const out = base.extract(doc);
     if ("refused" in out) return out;
-    if (out.value.type === "url" && !out.value.value.startsWith("https://"))
+    const { ref } = out.value;
+    if (ref.type === "url" && !ref.value.startsWith("https://"))
       return {
         refused: true,
         haltClass: "verification-failure",
         code: "ucp/insecure-terms-url",
-        detail: `a terms link must be HTTPS — an http: reference is rewritable in transit: ${out.value.value}`,
+        detail: `a terms link must be HTTPS — an http: reference is rewritable in transit: ${ref.value}`,
       };
     return out;
   },