feat(routines): inventory pinned G36 source trees (#71)

Author: jscott3201

.github/workflows/verify.yml

@@ -17,13 +17,33 @@ jobs:
         id: pin
         run: echo "rev=$(cat cxf-library/ENGINE_PIN)" >> "$GITHUB_OUTPUT"
 
+      - name: Read G36 source pins
+        id: g36-source-pins
+        run: |
+          echo "release=$(cat cxf-library/routines/g36/SOURCE_RELEASE_PIN)" >> "$GITHUB_OUTPUT"
+          echo "development=$(cat cxf-library/routines/g36/SOURCE_DEVELOPMENT_PIN)" >> "$GITHUB_OUTPUT"
+
       - name: Checkout open-control engine at pin
         uses: actions/checkout@v4
         with:
           repository: jscott3201/open-control-engine
           ref: ${{ steps.pin.outputs.rev }}
           path: open-control
 
+      - name: Checkout Modelica Buildings release source at pin
+        uses: actions/checkout@v4
+        with:
+          repository: lbl-srg/modelica-buildings
+          ref: ${{ steps.g36-source-pins.outputs.release }}
+          path: modelica-buildings-release
+
+      - name: Checkout Modelica Buildings development source at pin
+        uses: actions/checkout@v4
+        with:
+          repository: lbl-srg/modelica-buildings
+          ref: ${{ steps.g36-source-pins.outputs.development }}
+          path: modelica-buildings-development
+
       - name: svg fitment lint
         working-directory: cxf-library
         run: python3 tools/lint/svg_fitment.py
@@ -38,6 +58,13 @@ jobs:
           python3 -m unittest discover -s tools/lint/tests -v
           python3 tools/lint/routines.py
 
+      - name: Verify G36 source inventory
+        working-directory: cxf-library
+        run: |
+          python3 tools/lint/g36_source.py --check \
+            --release-root ../modelica-buildings-release \
+            --development-root ../modelica-buildings-development
+
       - uses: dtolnay/rust-toolchain@stable
 
       - uses: Swatinem/rust-cache@v2

SCHEMA.md

@@ -22,7 +22,7 @@ cxf-library/
 ├── routines/                    # planned control-routine catalog
 │   ├── registry.json            # canonical class inventory
 │   ├── generated-registry.json  # executable deployment inventory
-│   └── g36/                     # G36 source pins, scope, and coverage
+│   └── g36/                     # G36 pins, source inventory, scope, and coverage
 ├── tools/verify/                # Rust harness: loads each rule into the engine, runs vectors
 ```
 
@@ -52,8 +52,9 @@ next free number, honoring any reservation.
 ## Routine catalog
 
 Routine contracts are independent of fault contracts. Nothing in this section
-changes a fault schema identifier or fault behavior. The L0 routine catalog is
-planned and non-executable.
+changes a fault schema identifier or fault behavior. The routine catalog is
+planned and non-executable. L1 adds source-tree evidence without adding a
+canonical class or executable deployment.
 
 Pin ownership is split by purpose:
 
@@ -73,20 +74,77 @@ retired and MUST be absent.
 `routines/registry.json` is the canonical class inventory. Its top-level object
 has exactly `schema` and `routines`; `schema` is
 `cxf-library/routine-registry/v2`. `routines` MUST be an array and MUST remain
-empty in L0. A scope anchor is not a canonical class. Actual class and
-subsequence identities are deferred to the pinned source inventory.
+empty in L1. A scope anchor is not a canonical class. The source inventory
+defined below records Git blobs; it does not identify Modelica classes or
+subsequences.
 
 `routines/generated-registry.json` is the only inventory that may eventually
 drive routine execution. Its top-level object has exactly `schema` and
 `deployments`; `schema` is
 `cxf-library/generated-routine-registry/v1`. `deployments` MUST be an array and
-MUST remain empty in L0. The verifier's `--routines` mode reads this file,
+MUST remain empty in L1. The verifier's `--routines` mode reads this file,
 accepts the empty array, and rejects nonempty arrays until the generated
 deployment contract is implemented.
 
 Canonical IDs MUST NOT encode fixed parameter values. Generated deployment IDs
 and row schemas are not defined by this version.
 
+### `routines/g36/source-inventory.json` (`cxf-library/g36-source-inventory/v1`)
+
+The source inventory records two independent Git-tree snapshots from
+`https://github.com/lbl-srg/modelica-buildings.git`. Its top-level object has
+exactly these keys in order: `schema`, `repository`, `source_root`,
+`inventory_scope`, `dependency_closure`, `license`, and `snapshots`.
+
+- `schema` is `cxf-library/g36-source-inventory/v1`;
+- `repository` is `https://github.com/lbl-srg/modelica-buildings.git`;
+- `source_root` is `Buildings/Controls/OBC/ASHRAE/G36`;
+- `inventory_scope` is `source-root-regular-files`; and
+- `dependency_closure` is `not-inventoried`.
+
+`license` has exactly `upstream_path`, `retained_path`, `git_blob_sha1`, and
+`sha256`, in that order. `upstream_path` is `Buildings/legal.html` and
+`retained_path` is `routines/g36/LICENSE-BUILDINGS.html`. The retained file MUST
+equal the Git blob bytes at both pins. `git_blob_sha1` uses
+`sha1:<40 lowercase hex>` and `sha256` uses `sha256:<64 lowercase hex>`.
+
+`snapshots` contains exactly two rows, ordered `release` then `development`.
+Each row has exactly these keys in order: `role`, `revision`,
+`root_tree_sha1`, `file_count`, `total_bytes`, `modelica_file_count`,
+`package_order_count`, and `files`. `revision` MUST equal the corresponding pin
+file. `root_tree_sha1` is the Git tree ID for `source_root`, encoded as
+`sha1:<40 lowercase hex>`.
+
+Each `files` row has exactly `path`, `mode`, `bytes`, `git_blob_sha1`, and
+`sha256`, in that order. Paths are full upstream repository-relative POSIX
+paths below `source_root`, sorted lexicographically and unique. Empty, `.`, and
+`..` path segments, absolute paths, backslashes, and control characters are
+invalid. Version 1 supports only regular `100644` Git blobs; other modes and
+object types MUST be rejected. `bytes` and both hashes are calculated from Git
+object bytes rather than working-tree files.
+
+`file_count` is the number of file rows, and `total_bytes` is the sum of their
+`bytes` values. `modelica_file_count` counts paths ending in `.mo`.
+`package_order_count` counts paths ending in `/package.order`; `package.order`
+content is not parsed or validated. All files remain in the inventory whether
+or not another source file names them.
+
+The release and development snapshots MUST remain separate. The inventory does
+not choose a snapshot for a future canonical class and MUST NOT use one as a
+fallback for the other. It inventories no dependency outside `source_root` and
+makes no claim about Modelica declarations, classes, package members,
+references, imports, inheritance, source-family mapping, or executable
+coverage.
+
+`tools/lint/g36_source.py --write` regenerates the inventory and retained legal
+notice from two supplied checkouts. `--check` verifies each checkout origin and
+exact HEAD, derives all records through Git object commands, and compares both
+tracked artifacts byte-for-byte without rewriting them. JSON uses two-space
+indentation, the field order above, and one final newline. It contains no
+timestamp, branch name, checkout path, or moving source identity. A source pin
+change requires regenerating both snapshots; generation fails if the pinned
+legal blobs or bytes differ.
+
 ### `routines/g36/scope.json` (`cxf-library/g36-scope/v1`)
 
 The scope manifest makes the Section 5 planning boundary discoverable without
@@ -131,7 +189,7 @@ The IDs, destinations, and reviewed planning dispositions are:
 | 5.21 | `G36-SCOPE-05-21` | `g36/plants/hot-water` | `independent-authoring` |
 | 5.22 | `G36-SCOPE-05-22` | `g36/fan-coil-units` | `upstream-partial` |
 
-These dispositions classify the L0 source plan; they do not identify a source
+These dispositions classify the source plan; they do not identify a source
 class or prove implementation. Destinations are safe repository-relative POSIX
 paths below `g36/`. Absolute paths, backslashes, empty segments, `.` segments,
 and `..` segments are invalid. The manifest reserves destinations without
@@ -142,19 +200,19 @@ requiring placeholder directories.
 Coverage has exactly `schema`, `profile`, `status`, `scope`, and `claims`.
 `schema` is `cxf-library/g36-coverage/v2`; `profile` and `status` MUST equal
 `scope.json`; `scope` is `scope.json`; and `claims` MUST be an empty array in
-L0. Coverage does not repeat scope rows or inventory and makes no completeness,
+L1. Coverage does not repeat scope rows or inventory and makes no completeness,
 implementation, or evidence claim.
 
-No `routine.cxf.jsonld` may appear below `routines/g36/` in L0. The retired
+No `routine.cxf.jsonld` may appear below `routines/g36/` in L1. The retired
 `routines/g36/generic/air-economizer-high-limits` fixed-variant path MUST be
 absent.
 
 ### Deferred routine contracts
 
 Canonical typed routine artifact schemas, the generated deployment bundle
-schema, semantic sidecars, source inventory, specialization, and executable
-deployments are deferred. This version defines no routine interface, vectors,
-provenance, source map, or executable CXF contract.
+schema, source-to-family and class mapping, semantic sidecars, specialization,
+and executable deployments are deferred. This version defines no routine
+interface, vectors, source map, or executable CXF contract.
 
 ## Design stance (why the pieces split this way)
 

routines/README.md

@@ -1,14 +1,18 @@
 # Routine catalog
 
-Status: **planned and non-executable**.
+Status: **source-inventoried and non-executable**.
 
-The L0 catalog separates three inventories:
+The L1 catalog separates planning, source evidence, and future routine
+inventories:
 
 - `g36/scope.json` records 22 Section 5 planning anchors and their intended
   destinations. Scope IDs are not canonical class IDs, and the destinations do
   not imply implemented classes or directories.
+- `g36/source-inventory.json` records every regular Git blob below the pinned
+  upstream G36 source root in separate release and development snapshots.
+  `g36/LICENSE-BUILDINGS.html` retains the legal notice shared by both pins.
 - `registry.json` is the canonical class inventory. It remains empty until the
-  source inventory identifies actual classes and subsequences.
+  class and subsequence inventory is defined.
 - `generated-registry.json` is the only future executable deployment inventory.
   It remains empty until the deployment bundle contract and specializer exist.
 
@@ -25,7 +29,22 @@ Revision ownership is explicit:
 The pin files are authoritative source identities. There is no donor pin in the
 catalog contract. See the routine catalog section in
 [`SCHEMA.md`](../SCHEMA.md) for exact shapes, scope identities, and path rules.
-Validate the catalog boundary from the repository root:
+
+The source inventory hashes Git object bytes, not working-tree files. It does
+not parse `package.order` or Modelica declarations and makes no claim about
+classes, package members, dependencies outside the source root, source-family
+mapping, or executable coverage.
+
+Check the inventory against separate upstream checkouts whose HEADs match the
+pin files:
+
+```sh
+python3 tools/lint/g36_source.py --check \
+  --release-root /path/to/modelica-buildings-release \
+  --development-root /path/to/modelica-buildings-development
+```
+
+Run the remaining catalog gates from the repository root:
 
 ```sh
 python3 -m unittest discover -s tools/lint/tests -v
@@ -34,5 +53,5 @@ cargo run --manifest-path tools/verify/Cargo.toml -- --routines
 ```
 
 Canonical typed artifact schemas, generated deployment bundles, semantic
-sidecars, source inventory, specialization, and executable deployments remain
-deferred.
+sidecars, source-to-family and class mapping, specialization, and executable
+deployments remain deferred.

routines/g36/LICENSE-BUILDINGS.html

@@ -0,0 +1,79 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+
+<body>
+
+<h1>License</h1>
+<p>
+Modelica Buildings Library. Copyright (c) 1998-2026
+Modelica Association,
+International Building Performance Simulation Association (IBPSA),
+The Regents of the University of California, through Lawrence Berkeley National Laboratory
+(subject to receipt of any required approvals from the U.S. Dept. of Energy) and
+contributors.
+All rights reserved.
+</p>
+<p>
+NOTICE.  This Software was developed under funding from the U.S. Department of Energy and
+the U.S. Government consequently retains certain rights.
+As such, the U.S. Government has been granted for itself and others acting on its behalf
+a paid-up, nonexclusive, irrevocable, worldwide license in the Software
+to reproduce, distribute copies to the public, prepare derivative works, and
+perform publicly and display publicly, and to permit other to do so.
+</p>
+<p>
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+</p>
+<ol>
+<li>
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+</li>
+<li>
+Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the distribution.
+</li>
+<li>
+Neither the names of the Modelica Association,
+International Building Performance Simulation Association (IBPSA),
+the University of California,
+Lawrence Berkeley National Laboratory,
+U.S. Dept. of Energy,
+nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+</li>
+</ol>
+<p>
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+</p>
+<p>
+You are under no obligation whatsoever to provide any bug fixes, patches,
+or upgrades to the features, functionality or performance of the source code
+("Enhancements") to anyone; however, if you choose to make your Enhancements
+available either publicly, or directly to Lawrence Berkeley National
+Laboratory, without imposing a separate written license agreement for such
+Enhancements, then you hereby grant the following license: a non-exclusive,
+royalty-free perpetual license to install, use, modify, prepare derivative
+works, incorporate into other computer software, distribute, and sublicense
+such enhancements or derivative works thereof, in binary and source code form.
+</p>
+<p>
+Note: The license is a revised 3 clause BSD license with an ADDED paragraph
+at the end that makes it easy to accept improvements.
+</p>
+
+</body>
+
+</html>