@integraledger/lcp-placement-ucp 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @integraledger/lcp-placement-ucp
+
+## 0.9.0
+
+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
+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.
+
+Development before this release happened in a private repository and is not reproduced here; no earlier
+version was ever available to install.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,14 @@
+Integra Protocol
+Copyright 2026 Integra Ledger
+
+This product includes software developed by Integra Ledger (https://integraledger.com).
+
+"Integra", "Integra Ledger", and the Integra logo are trademarks of Integra Ledger.
+Trademark use is not granted by the Apache License 2.0 (see Section 6).
+
+The Legal Context Protocol is co-stewarded by Integra Ledger and AAA-ICDR. This repository is a
+reference implementation of the standard's open layer; the specification itself is published at
+https://legalcontextprotocol.org/standard and is not part of this distribution.
+
+The vendored submodule under lib/commerce-payments is Coinbase's AuthCaptureEscrow and carries its own
+MIT licence at lib/commerce-payments/LICENSE.md. It is not covered by the Apache License above.

package/README.md

@@ -0,0 +1,125 @@
+# @integraledger/lcp-placement-ucp
+
+Places an LCP reference into a [UCP](https://ucp.dev) (Universal Commerce Protocol) checkout, and reads it
+back out.
+
+**Integrity is Tier A today, via a `policies[]` entry.** The canonical carrier is a policy entry tagged
+`com.integraledger.policy.legal_context`, carrying the reference under the reverse-DNS key
+`com.integraledger.legal_context`. `policies[]` is in UCP's **base** checkout schema, so it needs no
+negotiated intersection, no hosted schema at a namespace authority, and nothing the counterparty can prune.
+The `links[type=terms_of_service].url` entry is the declared **discovery** alias: it locates the terms, it
+attests nothing about them.
+
+An earlier release wrote into `extensions["com.integraledger.legal-context"]`. **UCP has no such map.**
+Verified at `universal-commerce-protocol/ucp` HEAD 2026-08-08: `checkout.json` has eighteen properties and
+`extensions` is not among them — its own description reads *"Base checkout schema. Extensions compose onto
+this using allOf."* Because the schema is `additionalProperties: true`, the write **landed on every document
+and was read by nothing**. A refused write is a bug report; an accepted write nobody reads is a placement
+that reports success forever while carrying no legal context at all.
+
+```bash
+npm install @integraledger/lcp-placement-ucp
+```
+
+| | |
+|---|---|
+| **Chain** | none — UCP settles through whatever payment method the checkout selects |
+| **Pattern** | `http-advisory` (LCP §8.3.7, Tier A) |
+| **Field** | `policies[type=com.integraledger.policy.legal_context]` — reference under `com.integraledger.legal_context` |
+| **Read also** | `links[type=terms_of_service].url` (discovery, tagged-array) |
+| **Carrier types** | `sha256`, `url` |
+| **Spec** | UCP checkout + policy schemas, re-verified at HEAD **2026-08-08** |
+
+## Use
+
+```ts
+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 ref = ucpPlacement.extract(checkout);
+```
+
+Both members are total: a refusal is a returned value, never a thrown exception.
+
+## Specification provenance — verified against the live host, 2026-07-29 — and it re-cut the package
+
+Read against the live spec at ucp.dev, version `2026-04-08` (`overview#capabilities`,
+`overview#namespace-governance`, `overview#intersection-algorithm`, and the checkout capability page), the
+gate falsified the completion plan's P1 twice:
+
+1. **Vendor capabilities are Tier A.** The plan specced a links-only placement on the premise that UCP's
+   strict schema rejects unregistered keys, making the integrity path Tier B. The live spec says the
+   opposite: "Vendors MUST use their own reverse-domain namespace for custom capabilities" — no central
+   registry, no maintainer approval. What replaces registration is **authority binding**: "the origin of
+   these URLs MUST match the namespace authority" and "Platform MUST validate this binding and SHOULD
+   reject capabilities where the spec origin does not match." Built as planned, this package would have
+   shipped a URL and no hash while a hash-bearing carrier was available the whole time.
+2. **`links[].type` is an OPEN set** ("Businesses MAY define custom types"), not the closed enum the plan
+   claimed — that enum is ACP's; an earlier reading conflated the two protocols. `links[]` is REQUIRED on checkout
+   responses; entries are `{type (req), url (req), title (opt)}`; `terms_of_service` is a recommended
+   well-known type, used here because it is the spelling counterparties already read.
+
+One more finding shapes the failure mode: negotiation **silently prunes** orphaned extensions ("Remove any
+capability where extends is set but none of its parent capabilities are in the intersection") — a vendor
+capability the counterparty did not declare disappears without a loud rejection, which is why the discovery
+alias exists and why `extract` falls to it.
+
+## A placement, not a binding
+
+UCP describes a checkout; settling it is the selected payment method's business. This package is a
+`ReferencePlacementAdapter` — two pure functions and a manifest, no ports, no chain, no lifecycle. Where the
+selected method is a bound rail, that rail binding welds the record; otherwise this placement is the
+record's whole protocol reach and reads with an honest `not-attempted` at settlement-enumeration.
+
+## The one rule the kit cannot know
+
+`makePlacement(UCP_PLACEMENT)` — `makePlacement` comes from [`@integraledger/lcp-binding-core`](../binding-core#readme) — is the whole adapter
+except for a single wrap on `extract`: a url-typed
+result that does not start with `https://` refuses `ucp/insecure-terms-url`, because an `http:` link is
+rewritable in transit and accepting one would put an unauthenticated document behind a reference the record
+cites. The wrap is scoped by TYPE — a sha256 answer is never blocked by a bad link sitting beside it; the
+`policies[]` entry wins over `links`, and the vectors pin exactly that.
+
+## `description` is required, and it is an object
+
+UCP's policy schema is `required: ["type", "description"]`, so an entry carrying only a tag and a reference
+is an invalid document. The manifest therefore declares `constants`, and the writer emits them:
+
+```jsonc
+{
+  "description": { "plain": "Terms of sale for this order, identified by a Legal Context Protocol reference…" },
+  "type": "com.integraledger.policy.legal_context",
+  "com.integraledger.legal_context": { "type": "sha256", "value": "0x…" }
+}
+```
+
+`description` is a **Description object** (`{plain|html|markdown}`, `minProperties: 1`), not a bare string.
+
+The constants are written only when the entry is **created**. If the counterparty already declared this
+policy type, they wrote their own prose, and overwriting it in order to place our reference would be an
+edit to their document nobody asked for — so `place` merges the reference in and leaves the description
+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)`
+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
+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. A deployment advertises under
+its own reverse-domain namespace; `org.legalcontextprotocol.*` is reserved for a TSC-ratified capability.
+
+---
+
+**Requires Node >= 24.** Part of the
+[Legal Context Protocol open layer](https://github.com/IntegraLedger/integra-protocol) — see the
+[documentation](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/index.md)
+and the
+[package index](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/reference.md).
+Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { UCP_PLACEMENT } from "./manifest.js";
+export { ucpPlacement } from "./placement.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { UCP_PLACEMENT } from "./manifest.js";
+export { ucpPlacement } from "./placement.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,88 @@
+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
+ * 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
+ * vendor capability under an authority-bound reverse-domain namespace is a real UCP surface — it is what
+ * `/.well-known/ucp` advertisement uses — but a checkout RESPONSE carries no map to read one back out of.
+ * Verified at
+ * `universal-commerce-protocol/ucp` HEAD 2026-08-08, `source/schemas/shopping/checkout.json` has eighteen
+ * properties — actions, attribution, buyer, context, continue_url, currency, expires_at, id, line_items,
+ * links, messages, order, payment, policies, signals, status, totals, ucp — and `extensions` is not among
+ * them. Its own description reads "Base checkout schema. Extensions compose onto this using allOf": UCP
+ * extensions surface as top-level fields via schema composition, not as entries in a map.
+ *
+ * **The failure mode was SILENCE, which is worse than rejection.** `checkout.json` is
+ * `additionalProperties: true`, so the write landed on every document and was read by nothing. A refused
+ * write is a bug report; an accepted write nobody reads is a placement that reports success forever while
+ * carrying no legal context at all.
+ *
+ * **`policies[]` is in the base schema and needs nothing negotiated.** Verified at HEAD
+ * (`source/schemas/shopping/types/policy.json`): `required: ["type", "description"]`,
+ * `additionalProperties: true`, and `type` is an open reverse-DNS vocabulary — "Businesses MAY define
+ * custom types in their own domain (e.g., `com.example.policy.price_match`). Platforms MUST tolerate
+ * unknown values." It is also per-transaction by the schema's own words: "A durable business rule about
+ * the items in a response … at the time of purchase." So the reference travels with the checkout it
+ * governs, with no negotiated intersection, no hosted schema at the namespace authority, and no
+ * capability the counterparty can silently prune.
+ *
+ * **`description` is REQUIRED, and it is an OBJECT.** An entry carrying only `type` and our reference
+ * fails UCP's own schema, so the container declares `constants` and the writer emits them — otherwise
+ * this placement would put an invalid document on the wire, which is the shape-assertion this seam
+ * refuses. `description` is a Description (`{plain|html|markdown}`, `minProperties: 1`), NOT a bare
+ * string. The constants are written only when the entry is CREATED: a counterparty that already declared
+ * this policy type wrote its own prose, and overwriting it to place our reference would be an edit to
+ * their document nobody asked for.
+ *
+ * **The reference field is reverse-DNS namespaced**, `com.integraledger.legal_context`, because
+ * `additionalProperties: true` tolerates an added key but UCP's own convention namespaces
+ * extension-contributed keys — `reverse_domain_name.json` names exactly that use. A bare `value` would be
+ * an unnamespaced claim on a shared object.
+ *
+ * **pattern is `http-advisory`, NOT `protocol-extension`, on the same reasoning applied to ACP.** UCP
+ * does nothing atrHash-aware with the entry — §8.3.6 means the HOST protocol's own verification and
+ * settlement procedure understands the hash, which no UCP implementation does. §8.3.6 is also Tier B by
+ * definition, which would misdescribe a carrier that works today against stock UCP. The schema rejects
+ * the protocol-extension/Tier-A pairing outright.
+ *
+ * **The vendor capability is not gone, it is just not the carrier.** `/.well-known/ucp` advertisement
+ * remains a real UCP surface and `discovery` implements it — that is where the authority-bound namespace
+ * reasoning belongs, and it is correct there. What was wrong was believing a checkout RESPONSE carries an
+ * `extensions` map to read it back out of.
+ *
+ * **The links entry is the declared DISCOVERY alias, and it has no `write` flag — deliberately.** §C.3's
+ * limitation is real: a vendor capability the counterparty did not declare is SILENTLY pruned from the
+ * negotiated intersection, so the deployment SHOULD publish terms at the `links` level too, where discovery
+ * does not depend on negotiation. But the links entry carries the terms URL — a DIFFERENT datum than the
+ * atrHash — and `place(ref, 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 with `terms_of_service` a
+ * recommended type — a conformant merchant publishes it as part of being a UCP merchant at all), and this
+ * placement READS it: extract falls to the alias when the capability was pruned, the `url` carrier type
+ * itself signalling discovery-not-integrity. The gate also found the "closed enum" claim false —
+ * `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 S7 fixed for `field`: 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.
+ *
+ * **`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
+ * `carrier-type-not-permitted` without it. The capability's own schema (ours, published at the namespace
+ * authority when advertised) pins `sha256`; a url-typed reference in the capability is legal but adds
+ * nothing over the links entry. `ipfs`/`ar` are excluded: §C.3's example carries a sha256 and our schema
+ * should not advertise carrier forms no UCP counterparty has ever seen.
+ *
+ * UCP settles through whatever payment method the checkout selects, and that settlement is NOT this
+ * package's business — the same division ACP draws: a bound rail welds the record; otherwise this
+ * placement is the record's whole protocol reach and reads with an honest `not-attempted` at
+ * settlement-enumeration.
+ */
+export declare const UCP_PLACEMENT: PlacementManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

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

package/dist/manifest.js

@@ -0,0 +1,126 @@
+/**
+ * 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
+ * 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
+ * vendor capability under an authority-bound reverse-domain namespace is a real UCP surface — it is what
+ * `/.well-known/ucp` advertisement uses — but a checkout RESPONSE carries no map to read one back out of.
+ * Verified at
+ * `universal-commerce-protocol/ucp` HEAD 2026-08-08, `source/schemas/shopping/checkout.json` has eighteen
+ * properties — actions, attribution, buyer, context, continue_url, currency, expires_at, id, line_items,
+ * links, messages, order, payment, policies, signals, status, totals, ucp — and `extensions` is not among
+ * them. Its own description reads "Base checkout schema. Extensions compose onto this using allOf": UCP
+ * extensions surface as top-level fields via schema composition, not as entries in a map.
+ *
+ * **The failure mode was SILENCE, which is worse than rejection.** `checkout.json` is
+ * `additionalProperties: true`, so the write landed on every document and was read by nothing. A refused
+ * write is a bug report; an accepted write nobody reads is a placement that reports success forever while
+ * carrying no legal context at all.
+ *
+ * **`policies[]` is in the base schema and needs nothing negotiated.** Verified at HEAD
+ * (`source/schemas/shopping/types/policy.json`): `required: ["type", "description"]`,
+ * `additionalProperties: true`, and `type` is an open reverse-DNS vocabulary — "Businesses MAY define
+ * custom types in their own domain (e.g., `com.example.policy.price_match`). Platforms MUST tolerate
+ * unknown values." It is also per-transaction by the schema's own words: "A durable business rule about
+ * the items in a response … at the time of purchase." So the reference travels with the checkout it
+ * governs, with no negotiated intersection, no hosted schema at the namespace authority, and no
+ * capability the counterparty can silently prune.
+ *
+ * **`description` is REQUIRED, and it is an OBJECT.** An entry carrying only `type` and our reference
+ * fails UCP's own schema, so the container declares `constants` and the writer emits them — otherwise
+ * this placement would put an invalid document on the wire, which is the shape-assertion this seam
+ * refuses. `description` is a Description (`{plain|html|markdown}`, `minProperties: 1`), NOT a bare
+ * string. The constants are written only when the entry is CREATED: a counterparty that already declared
+ * this policy type wrote its own prose, and overwriting it to place our reference would be an edit to
+ * their document nobody asked for.
+ *
+ * **The reference field is reverse-DNS namespaced**, `com.integraledger.legal_context`, because
+ * `additionalProperties: true` tolerates an added key but UCP's own convention namespaces
+ * extension-contributed keys — `reverse_domain_name.json` names exactly that use. A bare `value` would be
+ * an unnamespaced claim on a shared object.
+ *
+ * **pattern is `http-advisory`, NOT `protocol-extension`, on the same reasoning applied to ACP.** UCP
+ * does nothing atrHash-aware with the entry — §8.3.6 means the HOST protocol's own verification and
+ * settlement procedure understands the hash, which no UCP implementation does. §8.3.6 is also Tier B by
+ * definition, which would misdescribe a carrier that works today against stock UCP. The schema rejects
+ * the protocol-extension/Tier-A pairing outright.
+ *
+ * **The vendor capability is not gone, it is just not the carrier.** `/.well-known/ucp` advertisement
+ * remains a real UCP surface and `discovery` implements it — that is where the authority-bound namespace
+ * reasoning belongs, and it is correct there. What was wrong was believing a checkout RESPONSE carries an
+ * `extensions` map to read it back out of.
+ *
+ * **The links entry is the declared DISCOVERY alias, and it has no `write` flag — deliberately.** §C.3's
+ * limitation is real: a vendor capability the counterparty did not declare is SILENTLY pruned from the
+ * negotiated intersection, so the deployment SHOULD publish terms at the `links` level too, where discovery
+ * does not depend on negotiation. But the links entry carries the terms URL — a DIFFERENT datum than the
+ * atrHash — and `place(ref, 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 with `terms_of_service` a
+ * recommended type — a conformant merchant publishes it as part of being a UCP merchant at all), and this
+ * placement READS it: extract falls to the alias when the capability was pruned, the `url` carrier type
+ * itself signalling discovery-not-integrity. The gate also found the "closed enum" claim false —
+ * `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 S7 fixed for `field`: 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.
+ *
+ * **`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
+ * `carrier-type-not-permitted` without it. The capability's own schema (ours, published at the namespace
+ * authority when advertised) pins `sha256`; a url-typed reference in the capability is legal but adds
+ * nothing over the links entry. `ipfs`/`ar` are excluded: §C.3's example carries a sha256 and our schema
+ * should not advertise carrier forms no UCP counterparty has ever seen.
+ *
+ * UCP settles through whatever payment method the checkout selects, and that settlement is NOT this
+ * package's business — the same division ACP draws: a bound rail welds the record; otherwise this
+ * placement is the record's whole protocol reach and reads with an honest `not-attempted` at
+ * settlement-enumeration.
+ */
+export const UCP_PLACEMENT = {
+    protocol: "ucp",
+    pattern: "http-advisory",
+    tier: "A",
+    encoding: "reference-object",
+    container: {
+        kind: "tagged-array",
+        at: "policies",
+        tagField: "type",
+        tag: "com.integraledger.policy.legal_context",
+        valueField: "com.integraledger.legal_context",
+        // `description` is REQUIRED by UCP's policy schema alongside `type`, so an entry without one is an
+        // invalid document. Verified at UCP HEAD 2026-08-08 (source/schemas/shopping/types/policy.json):
+        // `required: ["type","description"]`, and `description` is a Description OBJECT — {plain|html|markdown},
+        // minProperties 1 — not a bare string.
+        constants: {
+            description: {
+                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.",
+            },
+        },
+    },
+    field: "policies[type=com.integraledger.policy.legal_context]",
+    readAlso: [
+        {
+            path: "links[type=terms_of_service].url",
+            encoding: "bare-value",
+            bareType: "url",
+            carrierClass: "discovery",
+            container: {
+                kind: "tagged-array",
+                at: "links",
+                tagField: "type",
+                tag: "terms_of_service",
+                valueField: "url",
+            },
+        },
+    ],
+    carrierTypes: ["sha256", "url"],
+    specRef: "UCP checkout — policies[] entry under a reverse-DNS custom type (source/schemas/shopping/types/policy.json: base schema, required [type, description], additionalProperties true, type an open reverse-DNS vocabulary whose unknown values platforms MUST tolerate); checkout links[] entry typed terms_of_service (both re-verified at HEAD 2026-08-08: see README)",
+};
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;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"}

package/dist/placement.d.ts

@@ -0,0 +1,23 @@
+import { type ReferencePlacementAdapter } from "@integraledger/lcp-binding-core";
+/**
+ * The UCP reference placement — the kit plus ONE protocol rule the kit cannot know.
+ *
+ * `makePlacement(UCP_PLACEMENT)` supplies everything structural: the dotted-key capability write (the
+ * container's `segments` make `com.integraledger.legal-context` ONE key, not four), the tagged-array read of
+ * the `links` discovery alias, strength-ordered extraction, purity, and every refusal the vectors pin. This
+ * file adds only the rule that is UCP's semantics rather than any container's mechanics: **a terms link must
+ * be HTTPS.** An `http:` URL is rewritable in transit, so accepting one would put an unauthenticated document
+ * behind a reference the record cites.
+ *
+ * This is the composition S7 anticipates — 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.
+ *
+ * **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
+ * strength order. The vector "the capability WINS over links when both are present — even when the link is
+ * http:" pins exactly this. The scope is by TYPE, not by which carrier answered: a url-typed reference is
+ * legal in the capability too, and an http: URL there is exactly as rewritable as one in `links`.
+ */
+export declare const ucpPlacement: ReferencePlacementAdapter;
+//# sourceMappingURL=placement.d.ts.map

package/dist/placement.d.ts.map

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,EAAE,yBAc1B,CAAC"}

package/dist/placement.js

@@ -0,0 +1,40 @@
+import { makePlacement, } from "@integraledger/lcp-binding-core";
+import { UCP_PLACEMENT } from "./manifest.js";
+const base = makePlacement(UCP_PLACEMENT);
+/**
+ * The UCP reference placement — the kit plus ONE protocol rule the kit cannot know.
+ *
+ * `makePlacement(UCP_PLACEMENT)` supplies everything structural: the dotted-key capability write (the
+ * container's `segments` make `com.integraledger.legal-context` ONE key, not four), the tagged-array read of
+ * the `links` discovery alias, strength-ordered extraction, purity, and every refusal the vectors pin. This
+ * file adds only the rule that is UCP's semantics rather than any container's mechanics: **a terms link must
+ * be HTTPS.** An `http:` URL is rewritable in transit, so accepting one would put an unauthenticated document
+ * behind a reference the record cites.
+ *
+ * This is the composition S7 anticipates — 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.
+ *
+ * **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
+ * strength order. The vector "the capability WINS over links when both are present — even when the link is
+ * http:" pins exactly this. The scope is by TYPE, not by which carrier answered: a url-typed reference is
+ * legal in the capability too, and an http: URL there is exactly as rewritable as one in `links`.
+ */
+export const ucpPlacement = {
+    ...base,
+    extract(doc) {
+        const out = base.extract(doc);
+        if ("refused" in out)
+            return out;
+        if (out.value.type === "url" && !out.value.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}`,
+            };
+        return out;
+    },
+};
+//# sourceMappingURL=placement.js.map

package/dist/placement.js.map

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;GAmBG;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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@integraledger/lcp-placement-ucp",
+  "version": "0.9.0",
+  "description": "Places an LCP reference into a UCP (Universal Commerce Protocol) checkout, and reads it back.",
+  "keywords": [
+    "lcp",
+    "legal-context-protocol",
+    "legal-terms",
+    "agentic-commerce",
+    "placement",
+    "ucp"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IntegraLedger/integra-protocol.git",
+    "directory": "packages/placement-ucp"
+  },
+  "bugs": {
+    "url": "https://github.com/IntegraLedger/integra-protocol/issues"
+  },
+  "homepage": "https://github.com/IntegraLedger/integra-protocol/tree/main/packages/placement-ucp#readme",
+  "dependencies": {
+    "@integraledger/lcp-binding-core": "0.9.0"
+  },
+  "devDependencies": {
+    "@cfworker/json-schema": "4.1.1",
+    "@types/node": "24.13.3",
+    "vitest": "4.1.10"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { UCP_PLACEMENT } from "./manifest.js";
+export { ucpPlacement } from "./placement.js";

package/src/manifest.ts

@@ -0,0 +1,129 @@
+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
+ * 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
+ * vendor capability under an authority-bound reverse-domain namespace is a real UCP surface — it is what
+ * `/.well-known/ucp` advertisement uses — but a checkout RESPONSE carries no map to read one back out of.
+ * Verified at
+ * `universal-commerce-protocol/ucp` HEAD 2026-08-08, `source/schemas/shopping/checkout.json` has eighteen
+ * properties — actions, attribution, buyer, context, continue_url, currency, expires_at, id, line_items,
+ * links, messages, order, payment, policies, signals, status, totals, ucp — and `extensions` is not among
+ * them. Its own description reads "Base checkout schema. Extensions compose onto this using allOf": UCP
+ * extensions surface as top-level fields via schema composition, not as entries in a map.
+ *
+ * **The failure mode was SILENCE, which is worse than rejection.** `checkout.json` is
+ * `additionalProperties: true`, so the write landed on every document and was read by nothing. A refused
+ * write is a bug report; an accepted write nobody reads is a placement that reports success forever while
+ * carrying no legal context at all.
+ *
+ * **`policies[]` is in the base schema and needs nothing negotiated.** Verified at HEAD
+ * (`source/schemas/shopping/types/policy.json`): `required: ["type", "description"]`,
+ * `additionalProperties: true`, and `type` is an open reverse-DNS vocabulary — "Businesses MAY define
+ * custom types in their own domain (e.g., `com.example.policy.price_match`). Platforms MUST tolerate
+ * unknown values." It is also per-transaction by the schema's own words: "A durable business rule about
+ * the items in a response … at the time of purchase." So the reference travels with the checkout it
+ * governs, with no negotiated intersection, no hosted schema at the namespace authority, and no
+ * capability the counterparty can silently prune.
+ *
+ * **`description` is REQUIRED, and it is an OBJECT.** An entry carrying only `type` and our reference
+ * fails UCP's own schema, so the container declares `constants` and the writer emits them — otherwise
+ * this placement would put an invalid document on the wire, which is the shape-assertion this seam
+ * refuses. `description` is a Description (`{plain|html|markdown}`, `minProperties: 1`), NOT a bare
+ * string. The constants are written only when the entry is CREATED: a counterparty that already declared
+ * this policy type wrote its own prose, and overwriting it to place our reference would be an edit to
+ * their document nobody asked for.
+ *
+ * **The reference field is reverse-DNS namespaced**, `com.integraledger.legal_context`, because
+ * `additionalProperties: true` tolerates an added key but UCP's own convention namespaces
+ * extension-contributed keys — `reverse_domain_name.json` names exactly that use. A bare `value` would be
+ * an unnamespaced claim on a shared object.
+ *
+ * **pattern is `http-advisory`, NOT `protocol-extension`, on the same reasoning applied to ACP.** UCP
+ * does nothing atrHash-aware with the entry — §8.3.6 means the HOST protocol's own verification and
+ * settlement procedure understands the hash, which no UCP implementation does. §8.3.6 is also Tier B by
+ * definition, which would misdescribe a carrier that works today against stock UCP. The schema rejects
+ * the protocol-extension/Tier-A pairing outright.
+ *
+ * **The vendor capability is not gone, it is just not the carrier.** `/.well-known/ucp` advertisement
+ * remains a real UCP surface and `discovery` implements it — that is where the authority-bound namespace
+ * reasoning belongs, and it is correct there. What was wrong was believing a checkout RESPONSE carries an
+ * `extensions` map to read it back out of.
+ *
+ * **The links entry is the declared DISCOVERY alias, and it has no `write` flag — deliberately.** §C.3's
+ * limitation is real: a vendor capability the counterparty did not declare is SILENTLY pruned from the
+ * negotiated intersection, so the deployment SHOULD publish terms at the `links` level too, where discovery
+ * does not depend on negotiation. But the links entry carries the terms URL — a DIFFERENT datum than the
+ * atrHash — and `place(ref, 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 with `terms_of_service` a
+ * recommended type — a conformant merchant publishes it as part of being a UCP merchant at all), and this
+ * placement READS it: extract falls to the alias when the capability was pruned, the `url` carrier type
+ * itself signalling discovery-not-integrity. The gate also found the "closed enum" claim false —
+ * `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 S7 fixed for `field`: 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.
+ *
+ * **`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
+ * `carrier-type-not-permitted` without it. The capability's own schema (ours, published at the namespace
+ * authority when advertised) pins `sha256`; a url-typed reference in the capability is legal but adds
+ * nothing over the links entry. `ipfs`/`ar` are excluded: §C.3's example carries a sha256 and our schema
+ * should not advertise carrier forms no UCP counterparty has ever seen.
+ *
+ * UCP settles through whatever payment method the checkout selects, and that settlement is NOT this
+ * package's business — the same division ACP draws: a bound rail welds the record; otherwise this
+ * placement is the record's whole protocol reach and reads with an honest `not-attempted` at
+ * settlement-enumeration.
+ */
+export const UCP_PLACEMENT: PlacementManifest = {
+  protocol: "ucp",
+  pattern: "http-advisory",
+  tier: "A",
+  encoding: "reference-object",
+  container: {
+    kind: "tagged-array",
+    at: "policies",
+    tagField: "type",
+    tag: "com.integraledger.policy.legal_context",
+    valueField: "com.integraledger.legal_context",
+    // `description` is REQUIRED by UCP's policy schema alongside `type`, so an entry without one is an
+    // invalid document. Verified at UCP HEAD 2026-08-08 (source/schemas/shopping/types/policy.json):
+    // `required: ["type","description"]`, and `description` is a Description OBJECT — {plain|html|markdown},
+    // minProperties 1 — not a bare string.
+    constants: {
+      description: {
+        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.",
+      },
+    },
+  },
+  field: "policies[type=com.integraledger.policy.legal_context]",
+  readAlso: [
+    {
+      path: "links[type=terms_of_service].url",
+      encoding: "bare-value",
+      bareType: "url",
+      carrierClass: "discovery",
+      container: {
+        kind: "tagged-array",
+        at: "links",
+        tagField: "type",
+        tag: "terms_of_service",
+        valueField: "url",
+      },
+    },
+  ],
+  carrierTypes: ["sha256", "url"],
+  specRef:
+    "UCP checkout — policies[] entry under a reverse-DNS custom type (source/schemas/shopping/types/policy.json: base schema, required [type, description], additionalProperties true, type an open reverse-DNS vocabulary whose unknown values platforms MUST tolerate); checkout links[] entry typed terms_of_service (both re-verified at HEAD 2026-08-08: see README)",
+};

package/src/placement.ts

@@ -0,0 +1,43 @@
+import {
+  makePlacement,
+  type ReferencePlacementAdapter,
+} from "@integraledger/lcp-binding-core";
+import { UCP_PLACEMENT } from "./manifest.js";
+
+const base = makePlacement(UCP_PLACEMENT);
+
+/**
+ * The UCP reference placement — the kit plus ONE protocol rule the kit cannot know.
+ *
+ * `makePlacement(UCP_PLACEMENT)` supplies everything structural: the dotted-key capability write (the
+ * container's `segments` make `com.integraledger.legal-context` ONE key, not four), the tagged-array read of
+ * the `links` discovery alias, strength-ordered extraction, purity, and every refusal the vectors pin. This
+ * file adds only the rule that is UCP's semantics rather than any container's mechanics: **a terms link must
+ * be HTTPS.** An `http:` URL is rewritable in transit, so accepting one would put an unauthenticated document
+ * behind a reference the record cites.
+ *
+ * This is the composition S7 anticipates — 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.
+ *
+ * **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
+ * strength order. The vector "the capability WINS over links when both are present — even when the link is
+ * http:" pins exactly this. The scope is by TYPE, not by which carrier answered: a url-typed reference is
+ * legal in the capability too, and an http: URL there is exactly as rewritable as one in `links`.
+ */
+export const ucpPlacement: ReferencePlacementAdapter = {
+  ...base,
+  extract(doc: unknown) {
+    const out = base.extract(doc);
+    if ("refused" in out) return out;
+    if (out.value.type === "url" && !out.value.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}`,
+      };
+    return out;
+  },
+};