Generate the deterministic recipe-wrangle runtime contract manifest

[mborodii-prog]

Related to #1195.

Adds a versioned runtime manifest

Changes

• Discover stock recipe operations from the actual runtime namespace, including nested operations, executable aliases, and reserved recipe names.

• Export signatures, public and internal parameters, defaults, embedded schemas, and supported recipe controls.

• Record the package version and full source commit SHA.

• Validate the generated manifest against the version 0.1 JSON Schema.

• Generate a SHA-256 checksum alongside the manifest.

• Preserve the original --output option and default output filename.

• Update runtime-manifest documentation and release instructions.

Tagged exports verify that the selected tag, package version, and checkout commit agree. Uncommitted runtime or exporter changes are rejected unless explicitly generating a local preview.

Catalog identity support

Adds wrangles.utils.catalog_identity to attach an already allocated catalog ID to a callable.

The exporter preserves this ID as a decimal string, validates PostgreSQL BIGINT bounds, and rejects duplicate identities. Functions without an annotation are exported without catalog_id.

This PR does not allocate IDs or add annotations to existing operations.

Local examples

Install the required dependencies:

python -m pip install -r requirements-full.txt jsonschema pytest

Generate a validated manifest from committed source:

python schema/generate_wrangle_manifest.py --artifact-dir output_files/runtime-manifest

Generate a development preview containing uncommitted changes:

python schema/generate_wrangle_manifest.py --allow-dirty --artifact-dir output_files/runtime-manifest

Output:

output_files/runtime-manifest/


├── wrangles-runtime-manifest.json


└── wrangles-runtime-manifest.json.sha256

Workflow integration

Both ci.yml and publish-tagged.yml run the focused tests, generate the manifest, and upload:

• schema: recipe schema, legacy manifest filename, and manifest validation schema.

• runtime-manifest: manifest JSON and SHA-256 checksum.

CI produces preview artifacts. Successful stable tagged-release runs provide the version-specific runtime contract.

For this same-repository feature PR only, the temporary preview sync waits for schema validation and build, verifies the artifact checksum, then commits and pushes the two runtime manifest files directly to Wrangles-Docs main. It skips unchanged files and never force-pushes. It does not create a Docs PR or request Pull requests permissions. This writes a source PR preview to Docs main before the WranglesPY PR is merged. The GitHub App needs Contents write and authorization under Docs main branch rules; the workflow does not alter protection. Remove the temporary job or agree on a permanent trigger after the delivery test.

Automatic download, Registry content updates, and import into Wrangles-Docs remain part of wrangleworks/Wrangles-Docs#35. DEV/RC exports and GitHub Release assets are outside this change.

Validation

• 34 focused tests passed after rebasing onto current main: python -m pytest -c pytest-local.ini tests/test_wrangle_runtime_manifest.py -q. The pinned Docs lookup contract explicitly expects the current deprecation description; the historical fixture remains unchanged and every other field is still compared exactly.

• Both workflows passed actionlint.

• Tag verification passed with shallow checkouts for lightweight and annotated tags.

• Updated direct-push workflow passed YAML parsing and actionlint v1.7.12 (ShellCheck unavailable locally).

• Previous preview sync failed with GH013 on its protected target branch; end-to-end direct publishing to Docs main remains to be verified by the new CI run. The extra Pull requests token permission that caused HTTP 422 has been removed.