catincloud-crosslink 0.1.0__py3-none-any.whl

catincloud_crosslink-0.1.0.dist-info/METADATA

@@ -0,0 +1,323 @@
+Metadata-Version: 2.5
+Name: catincloud-crosslink
+Version: 0.1.0
+Summary: A project format reduced from an orchestrated asset graph, and the write path back to it
+Project-URL: Homepage, https://github.com/catincloud-labs/crosslink
+Project-URL: Repository, https://github.com/catincloud-labs/crosslink
+Project-URL: Issues, https://github.com/catincloud-labs/crosslink/issues
+Project-URL: Changelog, https://github.com/catincloud-labs/crosslink/blob/main/CHANGELOG.md
+Author: David Anaya
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: asset-graph,conformance,dagster,dbt,drift,project-format
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: conformance
+Requires-Dist: pytest>=8.4; extra == 'conformance'
+Provides-Extra: generate
+Requires-Dist: anthropic>=1.0; extra == 'generate'
+Provides-Extra: service
+Requires-Dist: catincloud-ration==0.2.1; extra == 'service'
+Provides-Extra: test
+Requires-Dist: pytest>=8.4; extra == 'test'
+Description-Content-Type: text/markdown
+
+# crosslink
+
+A project format reduced from an orchestrated asset graph - and the write path
+back to it.
+
+Copyright 2026 David Anaya. Apache-2.0.
+
+## What this is
+
+Modern transformation tooling assumes a project is a directory of files. An orchestrated
+asset graph is not that - it is a live object graph whose source of truth is the code
+that builds it. The two describe the same warehouse and cannot read each other.
+
+Reducing the graph into something a project-shaped consumer can **read** is
+solved, and that reduction is half of what this package contains. The way
+back is the harder half: when a consumer wants to change something, the
+change cannot be applied to the reduction, because the reduction is
+regenerated from code. So a change is proposed against the code (ADR-0002)
+and verified against the reduction it claims to change (ADR-0003); the
+Status section below says which steps of that path are built.
+
+Closing that loop is what this repository is for. The interesting property is that the
+two halves need each other - the reduction is what makes a proposed change *checkable*.
+Apply a candidate change, rebuild, re-reduce, and compare against the delta you asked
+for. The read side is the acceptance test for the write side.
+
+## What it offers, and what it does not
+
+Three things: the package; the contract a project format is judged by,
+`crosslink.conformance`, with the formats built to fail it,
+`crosslink.conformance_calibration`, shipped beside it; and the suite under
+`tests/`.
+
+The calibration is evidence about the contract, not about your format: it
+shows the contract refusing three formats that are wrong on purpose. A format
+conforms only when the contract has judged that format. Where this README and
+the contract disagree, the contract and its calibration are right.
+
+No guarantee and no support are promised. The write path ships as a mechanism,
+and nothing here says what it will do against a repository of yours.
+
+## Installing
+
+The distribution is named `catincloud-crosslink`, and it imports as
+`crosslink`:
+
+```bash
+pip install catincloud-crosslink
+```
+
+**Do not `pip install crosslink`.** That name on PyPI belongs to an unrelated
+project, which installs a top-level `crosslink` package of its own, so the two
+cannot share an environment and the wrong one imports without complaint.
+
+No release has been uploaded yet. Until one is, install from a clone:
+
+```bash
+git clone https://github.com/catincloud-labs/crosslink.git
+cd crosslink
+pip install .
+```
+
+## Status
+
+The read side is in place and passes its suite - and so is every step of the
+write path `docs/ROADMAP.md` sequences: reduction, self-consistency findings,
+the typed delta, the oracle harness, bounded patch generation, and the delivery
+adapter that renders a verified proposal as a pull request. What is still not
+implemented is the format-side half of tier 3: no format yet *receives* an edit
+through `propose_edits()`. The machinery that produces and proves a proposal
+exists; the contract it would hand the proposal to is declared only.
+
+| tier | contract | state |
+| --- | --- | --- |
+| 1 | `declarations()` - what the project declares | implemented - `DagsterProject`, `DbtProject` |
+| 2 | `+ fingerprint()` - what it looks like right now | implemented - both formats |
+| 3 | `+ propose_edits()` - what may be written back | **declared only** - no format serves it |
+
+Tier 3 is the point of the project and is deliberately the last thing standing.
+
+## Records
+
+Design decisions live in `docs/adr/` - immutable once merged; to change one,
+add a new record that supersedes it and link both directions. Each record
+carries a `## Do not implement until` section, and its checkboxes are
+load-bearing: the `adr preconditions` check refuses a citation of a record
+whose boxes are open, so tick one only when the named observable has been
+observed.
+
+The four records under `docs/adr/` were reworded once, on 2026-11-11, for
+publication: passages that pointed at private history were cut or rewritten,
+characters outside ASCII were replaced, and no status, decision or constraint
+changed. Each record says so in a dated note at its head, and the originals
+stand in the private repository's history.
+
+A bare `ADR-NNNN` in this repository names a record in **this** `docs/adr/`.
+A record in another repository's corpus is always cited with its repository
+named.
+
+## Layout
+
+```text
+src/crosslink/
+  __init__.py      the package surface - what `import crosslink` exports
+  model.py         the neutral project model
+  protocol.py      the tiered seam - tier 3 is declared here
+  context.py       how a project is located and built
+  declarations.py  declared keys, joins, semantics, sources
+  project.py       reduction from an asset graph - DagsterProject
+  dbt.py           the second format - DbtProject, tiers 1 and 2
+  conformance.py   an importable contract for project formats
+  conformance_calibration.py  formats built to fail that contract, shipped beside it
+  findings.py      self-consistency findings, computed from one snapshot
+  delta.py         the typed delta between two declaration snapshots
+  verify.py        the oracle harness: sandbox apply, re-reduce, compare
+  generate.py      bounded search against the oracle; the proposer is a callable
+  deliver.py       a verified proposal rendered as a pull request, or as files
+  wire.py          the versioned envelope and the fingerprint payload it carries
+  service.py       the comparer: two envelopes in, a drift verdict out
+  serve.py         the comparer as a process: framed fingerprints in, verdicts out
+  produce.py       the producer as a process: a graph reduced, published, framed, posted
+  PROVENANCE.md    what this shares with dagster-dex, and what each left out
+tests/
+docs/
+  adr/             the records
+  design/          what the subsystems look like today
+  ROADMAP.md       what is built, what is decided, what is parked
+```
+
+Derive the list rather than trusting it - `git ls-files src/crosslink docs` -
+and read a module's own docstring for what it is; the glosses above are those
+docstrings' first sentences, shortened.
+
+The read side shares its origin with the public `dagster-dex`, and depends on
+it nowhere - see `src/crosslink/PROVENANCE.md` for what is shared and how to
+see it.
+
+## Releases
+
+No release has been cut: no `v*` tag exists, and nothing is on PyPI under
+this project's name. *Installing*, above, says what to do until one is.
+
+A release is a signed `v*` tag, the upload of that tagged tree to PyPI as
+`catincloud-crosslink`, and the GitHub release for the tag.
+`.github/workflows/publish.yml` makes the upload and the GitHub release, from
+the tag and from nothing else, only after all of these have passed in the same
+run:
+
+- `.github/workflows/release.yml`, which it calls, has verified the tag's SSH
+  signature against `.github/allowed_signers`, read the tag's name as exactly
+  `v` and the version `pyproject.toml` carries at the tagged commit, and run
+  the suite there;
+- `.github/release/check-dist.py` has read the wheel and the sdist it is about
+  to upload: the distribution's name, its licence expression, no requirement
+  that names a URL, and the package's own `__version__` equal to the wheel's;
+- the stranger-shaped projects in `.github/strangers/` have judged that wheel
+  from a fresh environment: each format built to fail the contract fails
+  exactly the arms its defect is for, and a correct one passes them all.
+
+Each of those checks is also run on inputs built wrong on purpose, on every
+pull request and before every release, and the run fails unless each one is
+refused. Each uploaded file carries a PEP 740 attestation. After the upload
+the same run reads each file's provenance back from the index, and a
+provenance that names any publisher but that workflow, in this repository, in
+its `pypi` environment, turns the run red and withholds the GitHub release.
+The version in `pyproject.toml` at a commit no tag names is not a release.
+
+A release installs as *Installing* says, by the distribution name and never
+by the bare one. To judge a format of your own against the contract, install
+the `conformance` extra:
+
+```bash
+pip install "catincloud-crosslink[conformance]"
+```
+
+It adds pytest, the one dependency of the contract the package ships as
+`crosslink.conformance`; without it that module does not import.
+
+A tag is checked from a clone at that tag, with the scripts the workflow runs:
+
+```bash
+bash .github/release/verify-tag.sh <tag> .github/allowed_signers
+bash .github/release/check-version.sh <tag>
+```
+
+A bare `git verify-tag` is not the same check: it passes a signature made for
+another tag and moved to this one. The first script's exit 0 shows that a key
+`.github/allowed_signers` names signed a tag object carrying this tag's own
+name. That file travels in the same tree as the tag it vouches for, so it says
+nothing on its own about who holds the key.
+
+The metadata says `Development Status :: 3 - Alpha`, and it means it: while
+the major version is 0, a release may change what the contract decides.
+
+## Running the tests
+
+```bash
+uv run --frozen --python 3.12 --extra test --extra service pytest -q
+```
+
+That is the command CI's `tests` job runs, against the tracked `uv.lock`
+(`.github/workflows/checks.yml`). The `service` extra pins
+`catincloud-ration`, the distribution the public `catincloud-labs/ration`
+uploads to PyPI and which imports as `ration`, to one exact version. It needs
+no credential. Without the extra, `tests/test_serve.py` and
+`tests/test_produce.py` fail to collect, which is a red rather than a skip on
+purpose: a suite that cannot import the codec the comparer runs has not
+exercised the comparer.
+
+Where there is no project environment to freeze, the same suite runs with
+versions named on the command line, which are not the lock's:
+
+```bash
+uv run --no-project --python 3.12 --with-editable . --with pytest==8.4.1 \
+    --with 'catincloud-ration==<version>' \
+    python -m pytest tests -q
+```
+
+`<version>` is the one `pyproject.toml`'s `service` extra names. Never a bare
+`--with ration`, which takes PyPI's unrelated project of that name. This form
+re-resolves everything else, so it bypasses the lock that `CONTRIBUTING.md`
+calls mandatory: it is the recipe for a machine with no checkout to trust,
+not a second way to run CI.
+
+Nothing orchestrator-side is installed by either form, and that is the point: the package imports
+no orchestrator at all. `from_asset_graph` is duck-typed, so the coupling is to a shape
+rather than to a distribution. If a future change makes the suite need an orchestrator to
+pass, that is a coupling worth noticing rather than absorbing.
+
+## Running the comparer
+
+The long-lived half of the wire is `crosslink.serve`: a
+process that holds the last accepted fingerprint envelope as its standing
+objective and answers framed envelopes with drift verdicts, one JSON line per
+request on stdout. It needs the `service` extra, because it decodes the frame
+before the envelope and the frame codec lives in `ration`.
+
+```bash
+uv run --frozen --extra service python -m crosslink.serve \
+    --sender example --baseline ./baseline.json --bind 127.0.0.1:8100
+```
+
+`--sender` names each producer the process keeps a sequence ledger for (the
+`POST` path is `/<sender>`); `--baseline` is where the accepted bytes are
+kept so that a restart does not re-baseline, and its directory has to exist
+and be writable or the process refuses to start; `--bind` defaults to
+loopback. Where it runs, and behind what, is its deployment's to decide: the
+module offers no TLS and no authentication, and its docstring says so.
+
+## Running the producer
+
+The other half is `crosslink.produce`: one run reduces an asset
+graph, publishes its payload digest to a topic in a `ration` store, frames
+the envelope at the start of the epoch that publication returned, and posts
+it to a comparer. It writes one JSON line and exits; the cadence belongs to
+whoever deploys it.
+
+The reduction can be watched with no store and no comparer. The suite's own
+graph is four definitions and a carve (`tests/test_produce.py`), and
+`--dry-run` reduces it and prints the line:
+
+```bash
+PYTHONPATH=tests uv run --frozen --python 3.12 --extra test --extra service \
+    python -m crosslink.produce \
+    --load test_produce:GRAPH --carve test_produce:carve \
+    --name example \
+    --publish-topic example-fingerprint --publisher example-producer \
+    --post http://127.0.0.1:8100/example --dry-run
+```
+
+`--load` names the graph and `--carve` a function of the reduced tree's own
+that drops the definitions it does not want fingerprinted; both are module
+paths passed as arguments, so the source names no module of the tree it
+reduces. The line that comes back says `"event": "reduced"` and counts three
+models; drop `--carve` and it counts four. `--declared`, `--semantic` and
+`--sources` each name a directory of `*.yml` declarations, read by filename
+stem.
+
+A run without `--dry-run` needs three more things: the tree it reduces on
+`PYTHONPATH`, `RATION_DSN` in the environment, and a Postgres driver
+(`psycopg`) that neither this package nor `ration` declares as a dependency. Without the
+driver a real run stops at the store with `ModuleNotFoundError`, after the
+reduction. The suite does not prove that path: it injects
+`ration.memory.MemoryStore`.
+
+## Naming
+
+Three names, and they are not interchangeable:
+
+- **`crosslink`** is the repository and the import name.
+- **`catincloud-crosslink`** is the distribution name, the one to install.
+- **`crosslink` on PyPI** is someone else's project. See *Installing*.

catincloud_crosslink-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+crosslink/PROVENANCE.md,sha256=CoSBo99e3hYYj5I2nGWThHLIKwBPq-enE1srcrzFfmY,4047
+crosslink/__init__.py,sha256=fubQ2_GyTJrYtd91PzGLyzl8tXSN8epAF8inp_M4xY4,3599
+crosslink/conformance.py,sha256=aCpEjpHOv5EjnIcklnS9BP2e170WaZGZ-MOjL6X_new,17539
+crosslink/conformance_calibration.py,sha256=Ch3qRtuj9o1j8YUJ6ZBLRZoGH7bxK37joyJKghRZswY,9062
+crosslink/context.py,sha256=xwUXj1cLm-InM2C6XPiFO9vrab6NTL8Eu9qB1NzxJso,2747
+crosslink/dbt.py,sha256=ipEfDjA_Gf2iSpjfnVtWaXvc4EHBUozC2kvtXKXldPE,20886
+crosslink/declarations.py,sha256=YrtlkVSZETiAlTw1RZKThP0BoFMF4eByYs2Qsb-MgyY,15209
+crosslink/deliver.py,sha256=IxxtiuoaNJtR920D7SXthGIvMG6NA59j1Qtxs5tuShc,24774
+crosslink/delta.py,sha256=8ToZDxPI69DgiaZaaHokoUqBWEHCg9B4g4m8agvTr4g,19132
+crosslink/findings.py,sha256=fOmgkvi9P738cs7WZ-r4M4xMnd45O5AIwSAhAfo4UAo,11991
+crosslink/generate.py,sha256=2TBtPwiZsEJGHZlhGHVZNBOIiSk6phmtsLlDkylOg-g,21832
+crosslink/model.py,sha256=b0RoVY5IFz8XGu8xPOa2uXuiWhLapLUmmrcgJSznqFA,16684
+crosslink/produce.py,sha256=a_eCN1ekKBFXOrNQaBaWwkHJuDaBpS_fiPMYBJaLwcA,17785
+crosslink/project.py,sha256=eJBuB67NpZHzU9kn9q44xsfDRQk2r_sNTqSmeqnAhvA,11365
+crosslink/protocol.py,sha256=-8h-AlK9Sn7LXZTSH6Lqr462mD1vzvURYedFBVahuT4,5256
+crosslink/serve.py,sha256=L0uP_dlK-6xVfbZA3cFBxbuSsWziVjNjZakH7Zk50HU,19061
+crosslink/service.py,sha256=_zobsJCwZojSxOoaR8iRpV0-qWVNFmN7EJZaEfVFIJ4,5068
+crosslink/verify.py,sha256=Vo9k0N85LFybimHBPpimuxZfSVUqo1At9oF60lbZl94,7066
+crosslink/wire.py,sha256=zTMJqMhMOWHurfBrBPjy3IshJ5l-6ZcF-0Jnqi0kUXg,13108
+catincloud_crosslink-0.1.0.dist-info/METADATA,sha256=08mnhtCP8vmYjc537BI6el-TmiJ6GWe39ONmeSemCRg,14923
+catincloud_crosslink-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+catincloud_crosslink-0.1.0.dist-info/licenses/LICENSE,sha256=4e_rXXLWa1HuFHY66K4ESUYb6KmW0ztAJyIbGvVqnt4,11341
+catincloud_crosslink-0.1.0.dist-info/RECORD,,

catincloud_crosslink-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

catincloud_crosslink-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 David Anaya
+
+   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.

crosslink/PROVENANCE.md

@@ -0,0 +1,74 @@
+# Provenance
+
+This package's read side and the public
+[`dagster-dex`](https://github.com/catincloud-labs/dagster-dex) come from the
+same code. Neither depends on the other: nothing here imports `dagster_dex`,
+and `pyproject.toml` names no such requirement. This file says what the two
+share and what each left out, so that a port in either direction is a diff
+rather than archaeology.
+
+## What is shared, and how to see it
+
+Besides `__init__.py`, five modules carry the same name in both packages:
+`model.py`, `protocol.py`, `declarations.py`, `project.py` and
+`conformance.py`. The comparison below is against `dagster-dex`'s first tag,
+`v0.1.0`:
+
+    git clone https://github.com/catincloud-labs/dagster-dex
+    git -C dagster-dex checkout v0.1.0
+    git diff --no-index dagster-dex/src/dagster_dex/protocol.py src/crosslink/protocol.py
+
+Run the last command once per module. Both sides have moved since, so the
+diffs are not empty; what they show is the same docstrings and the same
+names, edited apart.
+
+| here | in `dagster-dex` at `v0.1.0` | what a diff shows |
+| --- | --- | --- |
+| `protocol.py` | `protocol.py` | the same three tiers, `ProjectSource`, `FingerprintedProject` and `EditableProject`, and the same `tier_of` |
+| `model.py` | `model.py` | the same neutral model, from `ProjectModel` to `ProjectDeclarations`. This side added the shared predicates and `layered_fingerprint`; that side has `SemanticField`, which this one does not |
+| `declarations.py` | `declarations.py` | the same three parsers: `parse_declarations`, `parse_semantics` and `parse_source_declarations` |
+| `project.py` | `project.py` | `DagsterProject` and the two unexported protocols it reads a graph through |
+| `conformance.py` | `conformance.py` | `ProjectSourceContract`, `FingerprintedProjectContract` and the fixture builders |
+| `context.py` | `dex.py` | `ProjectContext`. There it sits inside the engine boundary module; here it stands alone, because it is not engine-specific |
+
+## What each left out
+
+Not here, and in `dagster-dex`:
+
+- **`dex.py`**, the mapping onto the dex engine's model (`to_transform_layer`,
+  `transform_layer_notes`, `to_project_definitions`), and
+  `tests/test_dex_bridge.py`, which tests it. Whether this package stays
+  interoperable with that engine is an open decision, and an unused mapping
+  acquires callers. Re-adding it is a bounded, one-file job.
+- **`artifact.py`**, the transport that carries a reduced project as a file.
+
+Here, and not in `dagster-dex`: the second format (`dbt.py`), the write path
+(`findings.py`, `delta.py`, `verify.py`, `generate.py`, `deliver.py`), the
+wire and its two processes (`wire.py`, `service.py`, `serve.py`,
+`produce.py`), and the formats built to fail the contract
+(`conformance_calibration.py`).
+
+## Why two packages rather than one dependency
+
+The two are under different constraints, each readable in its own tree.
+`dagster-dex` is a plugin for one engine: its `requires-python` is `>=3.10`,
+and its `AGENTS.md` keeps the engine import to one module so that everything
+else runs with the engine uninstalled. This package targets no engine, has a
+3.12 floor, takes `ration` for its two processes, and is built around
+verifying a proposal against the reduction it claims to change (ADR-0003).
+
+They also answer tier 3 differently. `dagster-dex`'s `main` reaches it with
+`EditableDagsterProject`, whose edits land in hand-written declaration files
+(its `AGENTS.md` says why those and not the models). Here no format serves
+tier 3 yet, and a change is proposed against code (ADR-0002).
+
+Sharing the read side as a dependency would mean arguing every change to it
+against both sets of constraints. A port is still possible in either
+direction, as a diff, and it is a decision each time rather than a sync.
+
+## Copyright
+
+Both repositories are Apache-2.0, `Copyright 2026 David Anaya` (each one's
+`LICENSE`), so text moves between them without friction. Whether the holder
+should become a legal entity is an open question; it would touch the per-file
+headers as well as `LICENSE`.