@integraledger/lcp-placement-ucp 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @integraledger/lcp-placement-ucp
 
+## 0.16.0
+
+### Minor Changes
+
+- 3ca1d2b: UCP's HTTPS rule now applies to `place`, not only to `extract`.
+  
+  The placement wrapped `extract` alone, under a docblock reasoning that "`place` never writes the links
+  alias, so the write side has no URL to police". The write side does have one: the `policies[]` entry
+  `place` writes carries the reference itself, `url` is a permitted carrier type here, and `place` accepted an
+  `http:` url reference and emitted a document this very module's `extract` refuses. A placement that will
+  not read back the bytes it wrote fails a round trip on its own output.
+  
+  The terms URL was never the gap — the kit already refuses a non-https `termsUrl` at
+  `ucp/terms-url-malformed`. The reference was, and a url-typed reference inside a policies entry is exactly
+  as rewritable in transit as one in `links`. The rule is now stated once and applied in both directions.
+  
+  **This changes published behaviour**: `ucpPlacement.place` refuses `ucp/insecure-terms-url` where it
+  previously returned a written document.
+  
+  The corpus gains the write half of the rule and an https control beside it. 859 → 861; the corpus root
+  moved to `c2875add14f5f2bf…`.
+
+### Patch Changes
+
+- feab885: Five README examples that failed on their first line, and a gate that runs the examples.
+  
+  Each was the first thing a stranger runs, on the npmjs landing page:
+  
+  - `binding-evm-x402` opened with `getX402Deployment("base-sepolia-usdc")`; the keys are `base`,
+    `base-sepolia`, `avalanche`, `monad`. It threw.
+  - `discovery` told the reader to read `hashesAgree`; the field is `hashesMatch`, so the documented read is
+    `undefined` — falsy — and records a MISMATCH for a hash that matched, the exact defect the two-field
+    design exists to prevent.
+  - `placement-ucp`'s only usage example refused `ucp/terms-url-missing`: this protocol declares a terms-URL
+    slot, so an integrity-bearing reference needs one, and every sibling README passes it.
+  - `placement-ack` claimed a `url` carrier in the canonical slot "passes `requireIntegrity`". It did when
+    written; `requireIntegrity` now checks the value's type as well as the slot's declared class and returns
+    `undefined`. The narrower point that survives is stated instead.
+  - `binding-canton` documented a DAR filename, `lcp-anchor-0.9.0.dar`, that no build produces —
+    `daml.yaml` carries the package version, gated by a test. Both the README and `daml.yaml`'s own comment
+    now write the version as a glob, because a pinned number inside a copyable command goes stale at the
+    next bump and had already done so twice.
+  
+  The mechanism behind all five is that `check:docs` COMPILES fences and never runs them. `check:doc-calls`
+  runs the subset that can be run — a call of a workspace export whose every argument is a literal — and
+  refuses a throw or a returned `Refusal`. It also reads the inversion: a line the document annotates
+  `// throws` or `// refuses` must fail, so a demonstration that quietly starts succeeding is caught too.
+  Elided arguments (`"0x…"`) and calls inside a `try` are skipped as structurally not assertions. It refuses
+  an empty subject set, and it runs 30 calls across 74 fences today.
+- @integraledger/lcp-binding-core@0.16.0
+
+## 0.15.1
+
+### Patch Changes
+
+- Updated dependencies [431b8ec]
+  - @integraledger/lcp-binding-core@0.15.1
+
 ## 0.15.0
 
 ### Patch Changes
@@ -114,7 +172,7 @@ claimedClass`, so a record proving nothing — no settlement, no acceptance, no
   `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
+  being wholly scheme-private when x402 §6.1 reserved names inside it, and LCP §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
@@ -166,7 +224,7 @@ and a large number of documentation claims were corrected against the host speci
 First public release.
 
 `0.9.0` is deliberate: this is a release candidate for 1.0, not a preview. The implementation is complete
-against LCP v1.38 and certified by the conformance corpus, and the remaining distance to 1.0 is the
+against the published LCP specification and certified by the conformance corpus, and the remaining distance to 1.0 is the
 specification's own — the standard is still moving through its steering committee, and this package will not
 claim a stability its protocol has not yet promised.
 

package/README.md

@@ -36,12 +36,24 @@ npm install @integraledger/lcp-placement-ucp
 import { UCP_PLACEMENT, ucpPlacement } from "@integraledger/lcp-placement-ucp";
 
 declare const checkout: unknown; // the UCP checkout response, as received
-
-const placed = ucpPlacement.place({ ref: { type: "sha256", value: "0x…" } }, checkout);
+declare const atrHash: `0x${string}`;
+
+// `termsUrl` is REQUIRED beside an integrity-bearing reference on this protocol: the manifest declares a
+// terms-URL slot, and a counterparty holding only a hash cannot resolve it. Omitting it refuses
+// `ucp/terms-url-missing` rather than writing a reference nobody can follow.
+const placed = ucpPlacement.place(
+  {
+    ref: { type: "sha256", value: atrHash },
+    termsUrl: "https://seller.example/.well-known/legal-context.json",
+  },
+  checkout,
+);
 const ref = ucpPlacement.extract(checkout);
 ```
 
-Both members are total: a refusal is a returned value, never a thrown exception.
+Both members are total: a refusal is a returned value, never a thrown exception. Both also enforce one rule
+of UCP's own — a `url`-typed reference must be HTTPS — so `place` will not write what `extract` would
+refuse.
 
 ## Specification provenance — verified against the live host, 2026-07-29 — and it re-cut the package
 
@@ -116,7 +128,7 @@ present, the `url` carrier type itself signalling discovery-not-integrity.
 
 ## Provenance
 
-Cut against UCP `2026-04-08` (ucp.dev) and reconciled against LCP v1.37 §C.3; re-read against **v1.38 §C.3**
+Cut against UCP `2026-04-08` (ucp.dev) and reconciled against LCP §C.3; re-read against **LCP §C.3**
 on 2026-08-12, which now records `policies[]` as a Tier A carrier in the negotiated baseline — the carrier
 this package moved to. A deployment advertises under
 its own reverse-domain namespace; `org.legalcontextprotocol.*` is reserved for a TSC-ratified capability.

package/dist/manifest.d.ts

@@ -2,7 +2,7 @@ import type { PlacementManifest } from "@integraledger/lcp-binding-core";
 /**
  * UCP (Universal Commerce Protocol) reference placement, cut against the live spec (2026-04-08, ucp.dev —
  * overview §capabilities, §namespace-governance, §intersection-algorithm, and the checkout capability's
- * response schema), gate discharged 2026-07-29 against LCP v1.37 §C.3, and re-cut against the live UCP schemas and v1.38 §C.3
+ * response schema), gate discharged 2026-07-29 against LCP §C.3, and re-cut against the live UCP schemas and LCP §C.3
  * on 2026-08-08 when the canonical carrier moved.
  *
  * **THE CANONICAL CARRIER IS A `policies[]` ENTRY, AND UCP HAS NO `extensions` MAP TO WRITE INTO.** A

package/dist/manifest.js

@@ -1,7 +1,7 @@
 /**
  * UCP (Universal Commerce Protocol) reference placement, cut against the live spec (2026-04-08, ucp.dev —
  * overview §capabilities, §namespace-governance, §intersection-algorithm, and the checkout capability's
- * response schema), gate discharged 2026-07-29 against LCP v1.37 §C.3, and re-cut against the live UCP schemas and v1.38 §C.3
+ * response schema), gate discharged 2026-07-29 against LCP §C.3, and re-cut against the live UCP schemas and LCP §C.3
  * on 2026-08-08 when the canonical carrier moved.
  *
  * **THE CANONICAL CARRIER IS A `policies[]` ENTRY, AND UCP HAS NO `extensions` MAP TO WRITE INTO.** A

package/dist/placement.d.ts

@@ -12,9 +12,18 @@ import { type ReferencePlacementAdapter } from "@integraledger/lcp-binding-core"
  * behind a reference the record cites.
  *
  * This is the composition the kit is shaped for — generic mechanics, protocol-specific semantics layered on
- * top —
- * and it wraps `extract`, not `place`: `place` never writes the links alias (the terms URL is the
- * DEPLOYMENT's datum, not the reference — see the manifest), so the write side has no URL to police.
+ * top — and it wraps BOTH directions, because the rule is about the carrier and both directions carry one.
+ *
+ * ⛔ It wrapped `extract` alone until 2026-09-03, under the reasoning that "`place` never writes the links
+ * alias, so the write side has no URL to police". That was already false when it was written and became
+ * more so: the policies entry `place` writes carries the reference itself, `url` is a permitted carrier
+ * type here, and the kit's own terms-URL slot landed on the same entry. So `place` accepted an `http:`
+ * reference and emitted a document this very module's `extract` refuses — a placement that will not read
+ * back the bytes it wrote, and a round trip that fails on our own output rather than on a counterparty's.
+ * A url-typed reference inside a policies entry is exactly as rewritable in transit as one in `links`.
+ *
+ * The terms URL was never the gap: the kit already refuses a non-https `termsUrl` at
+ * `ucp/terms-url-malformed`. The REFERENCE was.
  *
  * **Scoped to url-typed results, deliberately.** A sha256 answer must never be blocked by a bad link sitting
  * beside it — the capability WINS over links, and refusing the winner for the loser's defect would invert the

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,yBAe1B,CAAC"}
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,yBAAyB,EAE/B,MAAM,iCAAiC,CAAC;AAgBzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,YAAY,EAAE,yBAY1B,CAAC"}

package/dist/placement.js

@@ -1,6 +1,17 @@
 import { makePlacement, } from "@integraledger/lcp-binding-core";
 import { UCP_PLACEMENT } from "./manifest.js";
 const base = makePlacement(UCP_PLACEMENT);
+/** The one rule, stated once: a url-typed reference on this protocol must be HTTPS. */
+function insecureTermsUrl(ref) {
+    if (ref.type !== "url" || ref.value.startsWith("https://"))
+        return null;
+    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: ${ref.value}`,
+    };
+}
 /**
  * The UCP reference placement — the kit plus ONE protocol rule the kit cannot know.
  *
@@ -14,9 +25,18 @@ const base = makePlacement(UCP_PLACEMENT);
  * behind a reference the record cites.
  *
  * This is the composition the kit is shaped for — generic mechanics, protocol-specific semantics layered on
- * top —
- * and it wraps `extract`, not `place`: `place` never writes the links alias (the terms URL is the
- * DEPLOYMENT's datum, not the reference — see the manifest), so the write side has no URL to police.
+ * top — and it wraps BOTH directions, because the rule is about the carrier and both directions carry one.
+ *
+ * ⛔ It wrapped `extract` alone until 2026-09-03, under the reasoning that "`place` never writes the links
+ * alias, so the write side has no URL to police". That was already false when it was written and became
+ * more so: the policies entry `place` writes carries the reference itself, `url` is a permitted carrier
+ * type here, and the kit's own terms-URL slot landed on the same entry. So `place` accepted an `http:`
+ * reference and emitted a document this very module's `extract` refuses — a placement that will not read
+ * back the bytes it wrote, and a round trip that fails on our own output rather than on a counterparty's.
+ * A url-typed reference inside a policies entry is exactly as rewritable in transit as one in `links`.
+ *
+ * The terms URL was never the gap: the kit already refuses a non-https `termsUrl` at
+ * `ucp/terms-url-malformed`. The REFERENCE was.
  *
  * **Scoped to url-typed results, deliberately.** A sha256 answer must never be blocked by a bad link sitting
  * beside it — the capability WINS over links, and refusing the winner for the loser's defect would invert the
@@ -26,19 +46,16 @@ const base = makePlacement(UCP_PLACEMENT);
  */
 export const ucpPlacement = {
     ...base,
+    place(ad, doc) {
+        // BEFORE the kit writes: a document that has already been written into is a document a caller may
+        // reasonably send, and refusing after building it would make the refusal advisory.
+        return insecureTermsUrl(ad.ref) ?? base.place(ad, doc);
+    },
     extract(doc) {
         const out = base.extract(doc);
         if ("refused" in out)
             return out;
-        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: ${ref.value}`,
-            };
-        return out;
+        return insecureTermsUrl(out.value.ref) ?? out;
     },
 };
 //# sourceMappingURL=placement.js.map

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,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"}
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,GAGd,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,IAAI,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;AAE1C,uFAAuF;AACvF,SAAS,gBAAgB,CAAC,GAAoB;IAC5C,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,sBAAsB;QACjC,IAAI,EAAE,wBAAwB;QAC9B,MAAM,EAAE,6EAA6E,GAAG,CAAC,KAAK,EAAE;KACjG,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,YAAY,GAA8B;IACrD,GAAG,IAAI;IACP,KAAK,CAAC,EAA6B,EAAE,GAAY;QAC/C,kGAAkG;QAClG,mFAAmF;QACnF,OAAO,gBAAgB,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,CAAC,GAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,SAAS,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;QACjC,OAAO,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;IAChD,CAAC;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integraledger/lcp-placement-ucp",
-  "version": "0.15.0",
+  "version": "0.16.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.15.0"
+    "@integraledger/lcp-binding-core": "0.16.0"
   },
   "devDependencies": {
     "@cfworker/json-schema": "4.1.1",

package/src/manifest.ts

@@ -3,7 +3,7 @@ import type { PlacementManifest } from "@integraledger/lcp-binding-core";
 /**
  * UCP (Universal Commerce Protocol) reference placement, cut against the live spec (2026-04-08, ucp.dev —
  * overview §capabilities, §namespace-governance, §intersection-algorithm, and the checkout capability's
- * response schema), gate discharged 2026-07-29 against LCP v1.37 §C.3, and re-cut against the live UCP schemas and v1.38 §C.3
+ * response schema), gate discharged 2026-07-29 against LCP §C.3, and re-cut against the live UCP schemas and LCP §C.3
  * on 2026-08-08 when the canonical carrier moved.
  *
  * **THE CANONICAL CARRIER IS A `policies[]` ENTRY, AND UCP HAS NO `extensions` MAP TO WRITE INTO.** A

package/src/placement.ts

@@ -1,11 +1,25 @@
 import {
+  type LegalContextAdvertisement,
+  type LegalContextRef,
   makePlacement,
   type ReferencePlacementAdapter,
+  type Refusal,
 } from "@integraledger/lcp-binding-core";
 import { UCP_PLACEMENT } from "./manifest.js";
 
 const base = makePlacement(UCP_PLACEMENT);
 
+/** The one rule, stated once: a url-typed reference on this protocol must be HTTPS. */
+function insecureTermsUrl(ref: LegalContextRef): Refusal | null {
+  if (ref.type !== "url" || ref.value.startsWith("https://")) return null;
+  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: ${ref.value}`,
+  };
+}
+
 /**
  * The UCP reference placement — the kit plus ONE protocol rule the kit cannot know.
  *
@@ -19,9 +33,18 @@ const base = makePlacement(UCP_PLACEMENT);
  * behind a reference the record cites.
  *
  * This is the composition the kit is shaped for — generic mechanics, protocol-specific semantics layered on
- * top —
- * and it wraps `extract`, not `place`: `place` never writes the links alias (the terms URL is the
- * DEPLOYMENT's datum, not the reference — see the manifest), so the write side has no URL to police.
+ * top — and it wraps BOTH directions, because the rule is about the carrier and both directions carry one.
+ *
+ * ⛔ It wrapped `extract` alone until 2026-09-03, under the reasoning that "`place` never writes the links
+ * alias, so the write side has no URL to police". That was already false when it was written and became
+ * more so: the policies entry `place` writes carries the reference itself, `url` is a permitted carrier
+ * type here, and the kit's own terms-URL slot landed on the same entry. So `place` accepted an `http:`
+ * reference and emitted a document this very module's `extract` refuses — a placement that will not read
+ * back the bytes it wrote, and a round trip that fails on our own output rather than on a counterparty's.
+ * A url-typed reference inside a policies entry is exactly as rewritable in transit as one in `links`.
+ *
+ * The terms URL was never the gap: the kit already refuses a non-https `termsUrl` at
+ * `ucp/terms-url-malformed`. The REFERENCE was.
  *
  * **Scoped to url-typed results, deliberately.** A sha256 answer must never be blocked by a bad link sitting
  * beside it — the capability WINS over links, and refusing the winner for the loser's defect would invert the
@@ -31,17 +54,14 @@ const base = makePlacement(UCP_PLACEMENT);
  */
 export const ucpPlacement: ReferencePlacementAdapter = {
   ...base,
+  place(ad: LegalContextAdvertisement, doc: unknown) {
+    // BEFORE the kit writes: a document that has already been written into is a document a caller may
+    // reasonably send, and refusing after building it would make the refusal advisory.
+    return insecureTermsUrl(ad.ref) ?? base.place(ad, doc);
+  },
   extract(doc: unknown) {
     const out = base.extract(doc);
     if ("refused" in out) return out;
-    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: ${ref.value}`,
-      };
-    return out;
+    return insecureTermsUrl(out.value.ref) ?? out;
   },
 };