rune-runtime 2.2.1__tar.gz → 3.0.0__tar.gz

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/CODE_OF_CONDUCT.md

@@ -1,3 +1,7 @@
+<!--
+Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+SPDX-License-Identifier: Apache-2.0
+-->
 # Code of Conduct for {project name}
 
 Please see the [Community Code of Conduct](https://www.finos.org/code-of-conduct).

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/ISSUE_TEMPLATE/Bug_report.md

@@ -1,3 +1,7 @@
+<!--
+Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+SPDX-License-Identifier: Apache-2.0
+-->
 ---
 name: 🐛 Bug Report
 about: If something isn't working as expected 🤔.

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/ISSUE_TEMPLATE/Feature_request.md

@@ -1,3 +1,7 @@
+<!--
+Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+SPDX-License-Identifier: Apache-2.0
+-->
 ---
 name: 🚀 Feature Request
 about: I have a suggestion (and may want to implement it 🙂)!

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/ISSUE_TEMPLATE/Support_question.md

@@ -1,3 +1,7 @@
+<!--
+Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+SPDX-License-Identifier: Apache-2.0
+-->
 ---
 name: 🤗 Support Question
 about: If you have a question about configuration, usage, etc. 💬

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/ISSUE_TEMPLATE/meeting-minutes.md

@@ -1,3 +1,7 @@
+<!--
+Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+SPDX-License-Identifier: Apache-2.0
+-->
 ---
 name: "\U0001F91D {project name} Meeting Minutes"
 about: To track {project name} meeting agenda and attendance

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/workflows/build-python-package.yml

@@ -1,3 +1,7 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 name: Build and Release Wheel
 
 on:

rune_runtime-3.0.0/.github/workflows/check-license-headers.yml

@@ -0,0 +1,39 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
+name: Check License Headers
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  license-headers:
+    name: Verify license headers
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install licenseheaders
+        run: pip install licenseheaders
+
+      - name: Check license headers
+        run: |
+          src/license/apply_headers.sh
+          git diff --exit-code || \
+            (echo "One or more files are missing a license header. Run 'src/license/apply_headers.sh' locally to fix." && \
+             exit 1)

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/workflows/cve-scanning-python.yml

@@ -1,3 +1,7 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 name: CVE Scanning for Python
 
 on:

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/workflows/license-scanning-python.yml

@@ -1,3 +1,7 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 name: License Scanning for Python
 
 on:

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/workflows/release.yml

@@ -1,3 +1,7 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 name: Publish to PyPi
 
 on:

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.github/workflows/run-tests.yml

@@ -1,3 +1,7 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 name: Run Unit Tests
 
 on:
@@ -5,6 +9,10 @@ on:
     branches:
       - main
       - develop
+  pull_request:
+    branches:
+      - main
+      - develop
 
 jobs:
   test:

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/.gitignore

@@ -28,3 +28,6 @@ rune.runtime-*.whl
 src/rune/runtime/version.py
 /.coverage
 src/rune_runtime.egg-info
+
+# local scratch files
+/.tmp/

rune_runtime-3.0.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
+repos:
+  - repo: local
+    hooks:
+      - id: license-headers-dirs
+        name: Add/check license headers (src, test, .github)
+        entry: licenseheaders
+        args: [-t, src/license/header.txt, --dir, src, --dir, test, --dir, .github]
+        language: python
+        additional_dependencies: [licenseheaders>=0.8.8]
+        types_or: [python, yaml, shell, toml]
+        pass_filenames: false
+      - id: license-headers-files
+        name: Add/check license headers (root files)
+        entry: licenseheaders
+        args: [-t, src/license/header.txt, --additional-extensions, python=.toml,
+               -f, build_wheel.sh, dev_clean_setup.sh, netlify.toml, pyproject.toml,
+               safety-policy.yml, .pre-commit-config.yaml]
+        language: python
+        additional_dependencies: [licenseheaders>=0.8.8]
+        types_or: [python, yaml, shell, toml]
+        pass_filenames: false

{rune_runtime-2.2.1/src/rune_runtime.egg-info → rune_runtime-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rune-runtime
-Version: 2.2.1
+Version: 3.0.0
 Summary: rune-runtime: the Rune DSL runtime for Python
 Author: Daniel Schwartz, Plamen Neykov, Others (See AUTHORS)
 License-Expression: Apache-2.0
@@ -30,6 +30,8 @@ Requires-Dist: pytest>=9.0.2; extra == "dev"
 Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.14.1; extra == "dev"
 Requires-Dist: types-python-dateutil>=2.9.0.20250809; extra == "dev"
+Requires-Dist: licenseheaders>=0.8.8; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
 Dynamic: license-file
 
 [![FINOS - Incubating](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-incubating.svg)](https://community.finos.org/docs/governance/Software-Projects/stages/incubating)
@@ -59,6 +61,20 @@ Use [dev_clean_setup.sh](https://github.com/Cloudrisk/rune-python-runtime/blob/m
 ```sh
 ./dev_clean_setup.sh
 ```
+
+This script installs all dev dependencies and registers the pre-commit hooks, including the license-header check. Every `.py` file under `src/` and `test/` must carry the Apache 2.0 SPDX header:
+
+```python
+# Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+# SPDX-License-Identifier: Apache-2.0
+```
+
+To add missing headers to all files at any time, run:
+
+```sh
+src/license/apply_headers.sh
+```
+
 ### 3. Build
 Use [build_wheel.sh](https://github.com/Cloudrisk/rune-python-runtime/blob/main/build_wheel.sh) to build the package
 ```sh

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/README.md

@@ -25,6 +25,20 @@ Use [dev_clean_setup.sh](https://github.com/Cloudrisk/rune-python-runtime/blob/m
 ```sh
 ./dev_clean_setup.sh
 ```
+
+This script installs all dev dependencies and registers the pre-commit hooks, including the license-header check. Every `.py` file under `src/` and `test/` must carry the Apache 2.0 SPDX header:
+
+```python
+# Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+# SPDX-License-Identifier: Apache-2.0
+```
+
+To add missing headers to all files at any time, run:
+
+```sh
+src/license/apply_headers.sh
+```
+
 ### 3. Build
 Use [build_wheel.sh](https://github.com/Cloudrisk/rune-python-runtime/blob/main/build_wheel.sh) to build the package
 ```sh

rune_runtime-3.0.0/benchmarks/benchmark_list_references.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+# SPDX-License-Identifier: Apache-2.0
+
+'''Compare reference-list overhead using the same models and installed dependencies.
+
+Run with the project interpreter. --source selects an extracted revision's src
+directory; omit it to measure the current checkout. Timings exclude model schema
+construction and report the best of --repeat runs independently for each round.
+'''
+import argparse
+import cProfile
+import gc
+import json
+import platform
+import sys
+import timeit
+from pathlib import Path
+from typing import Annotated
+
+
+def main() -> None:
+    '''Measure public read, write and validation operations on large model graphs.'''
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--source', type=Path)
+    parser.add_argument('--label', default='working-tree')
+    parser.add_argument('--size', type=int, default=2000)
+    parser.add_argument('--repeat', type=int, default=5)
+    parser.add_argument('--rounds', type=int, default=2)
+    parser.add_argument('--profile', type=Path)
+    args = parser.parse_args()
+    source = args.source or Path(__file__).resolve().parents[1] / 'src'
+    sys.path.insert(0, str(source.resolve()))
+
+    import pydantic
+    from rune.runtime.base_data_class import BaseDataClass
+    from rune.runtime.metadata import BaseReference
+
+    class Party(BaseDataClass):
+        _ALLOWED_METADATA = {'@key', '@key:external'}
+        name: str
+
+    class PlainBook(BaseDataClass):
+        parties: Annotated[list[Party], Party.serializer(), Party.validator(('@key:external',))]
+        items: Annotated[list[Party], Party.serializer(), Party.validator()]
+
+    class ReferenceBook(BaseDataClass):
+        parties: Annotated[list[Party], Party.serializer(), Party.validator(('@key:external',))]
+        items: Annotated[list[Party | BaseReference], Party.serializer(), Party.validator(('@ref:external',))]
+        _KEY_REF_CONSTRAINTS = {'items': {'@ref:external'}}
+
+    data = {
+        'parties': [{'@key:external': f'p{i}', 'name': f'Party {i}'} for i in range(args.size)],
+        'items': [{'name': f'Inline {i}'} for i in range(args.size)],
+    }
+    cases = [('no-references', PlainBook, data),
+             ('reference-capable-inline', ReferenceBook, data),
+             ('references', ReferenceBook, data | {
+                 'items': [{'@ref:external': f'p{i}'} for i in range(args.size)],
+             })]
+    result = {'label': args.label, 'python': platform.python_version(),
+              'pydantic': pydantic.__version__, 'source': str(source.resolve()),
+              'size': args.size, 'repeat': args.repeat, 'rounds': args.rounds, 'cases': {}}
+    for name, model_type, payload in cases:
+        encoded = json.dumps(payload)
+        model = model_type.rune_deserialize(encoded, validate_model=False)
+        operations = {
+            'read': lambda: model_type.rune_deserialize(encoded, validate_model=False),
+            'write': lambda: model.rune_serialize(validate_model=False),
+            'validate': model.validate_model,
+        }
+        measurements = {}
+        for operation, call in operations.items():
+            try:
+                call()
+            except Exception as error:
+                measurements[operation] = {'error': f'{type(error).__name__}: {error}'}
+                continue
+            timings = []
+            for _ in range(args.rounds):
+                gc.collect()
+                timings.append(min(timeit.repeat(call, number=1, repeat=args.repeat)))
+            measurements[operation] = {'seconds': timings}
+            if args.profile:
+                args.profile.mkdir(parents=True, exist_ok=True)
+                profile = cProfile.Profile()
+                profile.runcall(call)
+                profile.dump_stats(str(args.profile / f'{args.label}-{name}-{operation}.prof'))
+        result['cases'][name] = measurements
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == '__main__':
+    main()

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/build_wheel.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 
 function error
 {

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/dev_clean_setup.sh

@@ -1,4 +1,8 @@
 #!/bin/bash
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 
 function error
 {
@@ -34,3 +38,5 @@ ${PY_EXE} -m venv --clear .pydevenv || error
 
 
 python -m pip install -e .[dev] --config-settings editable_mode=compat || error
+
+pre-commit install || error

rune_runtime-3.0.0/docs/object-identity.md

@@ -0,0 +1,114 @@
+# Object identity and references
+
+Rune objects have an identity independently of the keys used to reference them.
+`as-key` requests the identity of its operand. Allocating a missing key records
+that identity; ordinary data writes are governed by ownership and copy-on-write
+(COW) isolation.
+
+## Principles
+
+1. Every object has an identity, even when it has no key.
+2. Distinct domain objects have distinct identities. For a given key type and
+   resolution scope, a key identifies at most one target.
+3. Keys represent identity. Multiple keys of different types can identify the
+   same object.
+4. Creating a key preserves the object's identity and ordinary data. It records
+   an identifier for the existing object.
+5. `as-key` requests the identity of its operand; it does not create a new target.
+6. A reference into the caller's graph grants read access and identity access.
+   Ordinary data writes require ownership.
+
+## Identity and keys
+
+Every object has an identity, including an object with no serialized key. Multiple
+keys can identify the same object, using different key types and resolution
+scopes. Allocating an additional key preserves the object's identity and ordinary
+data.
+
+Key uniqueness is evaluated using both the key type and the resolution scope.
+The same key text can occur under different types or in different scopes without
+implying that the targets share an identity.
+
+Key allocation can change the object's key metadata and register the key in a
+lookup table. This is intentional identity bookkeeping. A serialized object can
+therefore gain an `@key` without a change to its ordinary fields. Key allocation
+remains subject to the model's metadata permissions; having an identity does not
+make every type eligible for every kind of serialized key.
+
+The key identifies the existing target. Creating a key must not construct a
+different target solely to hold that key. A reference to a newly keyed object and
+a reference to an already keyed object have the same identity semantics.
+
+## Key selection for as-key
+
+Generated code implements `as-key` with `Reference(target)`. With no explicit key
+or key type, selection follows this order:
+
+1. Use the existing external key, if present.
+2. Otherwise reuse the existing internal key.
+3. Otherwise allocate an internal key for the existing target.
+
+| Existing keys | Serialized reference | Key allocation |
+| --- | --- | --- |
+| External `p1` | `{"@ref:external": "p1"}` | None |
+| Internal `i1` | `{"@ref": "i1"}` | None |
+| External `p1` and internal `i1` | `{"@ref:external": "p1"}` | None |
+| No external or internal key | `{"@ref": "<allocated key>"}` | Internal key |
+
+An explicit `key_type=KeyType.INTERNAL` selects an internal reference even when
+an external key exists. Supplying an explicit key selects that key using the
+constructor's existing key-type rules.
+
+Local keys are represented by `@key:scoped`. They require the appropriate
+resolution scope, so automatic selection currently excludes them. Creating a
+scoped reference remains explicit. Automatic selection would need a rule for
+checking the receiving scope.
+
+## Reference edges and key registries
+
+A reference occurrence records its key and key type on the receiving field or
+list entry. It exposes the target object without making that target a containment
+child of the receiver. The same target can occur both inline and by reference.
+
+The target holds its own key metadata. Key registries map keys to targets and are
+normally reached through the containment parent chain, with separate handling for
+scoped keys. An empty registry does not establish that the target has no key;
+key selection reads the target's metadata.
+
+Serialization writes a reference occurrence as its reference key, without
+embedding the target's data. The target's containment graph or external context
+provides the corresponding keyed object for resolution.
+
+## Ownership and COW
+
+Allocating an identity key alone does not require COW detachment. It may extend
+the existing target's key metadata and registry while leaving ordinary data
+unchanged. This exception is specific to identity keys and registration; it does
+not grant unrestricted access to other metadata or mutable values.
+
+The agreed access rule for generated functions is:
+
+> A reference into the caller's graph grants read access and identity access;
+> data writes require ownership.
+
+**Enforcing this access rule is follow-up work.** Current reference access can
+expose mutable targets; the external-key selection fix does not generally prevent
+data writes through borrowed references.
+
+The follow-up must protect nested objects, mutable collections and mutating
+methods reached through a borrowed reference. Replacing a reference field on an
+owned receiver is distinct from modifying the referenced target. References to
+contained targets within a graph managed by COW must retain the supported
+behavior of editing the detached graph while preserving its internal references.
+
+## Code and regression coverage
+
+Key selection and registration are implemented in
+[metadata.py](../src/rune/runtime/metadata.py). COW wrappers are implemented in
+[cow.py](../src/rune/runtime/cow.py).
+
+[test_keys_and_references.py](../test/test_keys_and_references.py) includes both
+generated-function reproductions from [issue #73](https://github.com/finos/rune-python-runtime/issues/73),
+along with coverage for existing keys and explicit internal selection.
+[test_list_cardinality_serialise.py](../test/test_list_cardinality_serialise.py)
+covers reference occurrences and the list form of `as-key`.

rune_runtime-3.0.0/netlify.toml

@@ -0,0 +1,6 @@
+#
+# Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+# SPDX-License-Identifier: Apache-2.0
+#
+[build]
+   ignore = "/bin/false"

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/pyproject.toml

@@ -1,3 +1,7 @@
+#
+# Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+# SPDX-License-Identifier: Apache-2.0
+#
 [build-system]
 requires = ["setuptools>=64", "setuptools_scm>=8", "wheel>=0.45.1", "pytest-runner>=6.0.1"]
 build-backend = "setuptools.build_meta"
@@ -15,7 +19,9 @@ optional-dependencies.dev = [
     "pytest>=9.0.2",
     "pytest-cov>=7.0.0",
     "pytest-mock>=3.14.1",
-    "types-python-dateutil>=2.9.0.20250809"
+    "types-python-dateutil>=2.9.0.20250809",
+    "licenseheaders>=0.8.8",
+    "pre-commit>=3.0.0"
 ]
 description = "rune-runtime: the Rune DSL runtime for Python"
 readme = "README.md"

{rune_runtime-2.2.1 → rune_runtime-3.0.0}/safety-policy.yml

@@ -1,3 +1,7 @@
+##
+## Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+## SPDX-License-Identifier: Apache-2.0
+##
 security:
     ignore-cvss-severity-below: 6
     ignore-cvss-unknown-severity: False

rune_runtime-3.0.0/src/license/apply_headers.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+# Applies the Apache 2.0 SPDX license header to all tracked source files.
+set -e
+TMPL="$(dirname "$0")/header.txt"
+licenseheaders -t "$TMPL" --dir src --dir test --dir .github
+licenseheaders -t "$TMPL" --additional-extensions python=.toml -f build_wheel.sh dev_clean_setup.sh netlify.toml pyproject.toml safety-policy.yml .pre-commit-config.yaml

rune_runtime-3.0.0/src/license/header.txt

@@ -0,0 +1,2 @@
+Copyright (c) 2023-2026 CLOUDRISK Limited and FT Advisory LLC
+SPDX-License-Identifier: Apache-2.0