tangle-cli 0.1.17__tar.gz → 0.1.19__tar.gz

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tangle-cli
-Version: 0.1.17
+Version: 0.1.19
 Summary: CLI for Tangle, the open-source ML pipeline orchestration platform
 Author: Alexey Volkov, Tangle authors, Volv Grebennikov
 Author-email: Alexey Volkov <alexey.volkov@ark-kun.com>, Volv Grebennikov <volv.grebennikov@shopify.com>
@@ -537,6 +537,34 @@ def greeting_pipeline(who: In[str], cfg) -> Out[str]:
 
 Task IDs default from the left-hand variable name at the call site, converted to title case. If there is no simple left-hand variable, or if you want a stable explicit label, call `.named("Task Id")` before invoking the task. Use `.bind(...)` to pre-fill task arguments and `.with_annotations({...})` to add per-task annotations.
 
+##### Root pipeline annotations
+
+`@pipeline(annotations={...})` writes the compiled pipeline's root `metadata.annotations` block. A caller that compiles programmatically can supply the block instead — typically from its own per-environment config file, so the values do not have to be hard-coded in source:
+
+```python
+from tangle_cli.pipelines import compile_pipeline_file
+
+compile_pipeline_file(
+    "pipeline.py",
+    "pipeline.yaml",
+    pipeline_annotations={"environment": "staging", "owner": "search-platform"},
+)
+```
+
+The same keyword exists on `tangle_cli.pipeline_compiler.compile_pipeline` and on `PipelineCompiler.compile_file`. There is no CLI flag: the source route already exists, and what the keyword adds is a programmatic/config route for the part of the block that varies by environment.
+
+Semantics:
+
+- **Per-key merge, caller wins.** `@pipeline(annotations={"author": "a", "version": "1.0"})` compiled with `pipeline_annotations={"version": "2.0", "environment": "staging"}` emits all three keys, with `version: "2.0"`. Source keys the caller does not mention are preserved, so invariants stay in source and only the varying subset is passed in.
+- **Omitted or `{}` is a no-op**, byte for byte — an empty mapping is not a destructive clear of the source block.
+- **Root only.** `subpipeline` children never inherit it, so child subgraph sidecar names, bytes, and component digests are unaffected. A child that wants annotations declares its own.
+- **Descriptive only.** Root metadata is not read by the orchestrator, so it cannot influence placement, routing, scheduling, or run identity. Use pipeline-run annotations for anything execution-bearing.
+- **`str -> str`, validated up front.** A non-mapping argument, a non-string key or value, an empty key, a `system/`-prefixed key (reserved by Tangle), or a template delimiter (`{{`, `{%`, `{#`) in a key or value raises `InvalidPipelineAnnotationsError` (a `CompileError`) before anything is imported or written. Annotations usually come from an untrusted config file, so the diagnostics name the key and the type and never echo a value. Values are baked into the compiled YAML and the stored pipeline definition: labels only, never secrets.
+
+The rules live in one place, `tangle_cli.schema_validation`: `check_annotations(mapping, policy=..., error_cls=...)` applied under a named `AnnotationPolicy`. `CALLER_ANNOTATION_POLICY` is the strict input policy described above; `DOCUMENT_ANNOTATION_POLICY` is the lenient policy every pipeline document is validated against (scalar-or-null values, no key rules), matching the schema and hand-authored YAML. Only the caller-supplied input surface is strict: existing documents are accepted exactly as before, and the document check still runs on the merged result, so annotations reaching the output by any route are validated.
+
+A distribution that reads these annotations from its own config file should call `check_annotations(mapping, policy=CALLER_ANNOTATION_POLICY, error_cls=...)` at config-parse time — passing its own error type and adding the config path and key to the message — so one user mistake produces one diagnostic instead of two competing ones. The compiler's own call is then the backstop for anything arriving by another route.
+
 ##### Conditional task execution
 
 Pipeline inputs used as conditions are ordinary `In[str]` values; there is no special conditional input annotation. Pass the value through the reserved task-call metadata keyword `is_enabled=`:

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/README.md

@@ -511,6 +511,34 @@ def greeting_pipeline(who: In[str], cfg) -> Out[str]:
 
 Task IDs default from the left-hand variable name at the call site, converted to title case. If there is no simple left-hand variable, or if you want a stable explicit label, call `.named("Task Id")` before invoking the task. Use `.bind(...)` to pre-fill task arguments and `.with_annotations({...})` to add per-task annotations.
 
+##### Root pipeline annotations
+
+`@pipeline(annotations={...})` writes the compiled pipeline's root `metadata.annotations` block. A caller that compiles programmatically can supply the block instead — typically from its own per-environment config file, so the values do not have to be hard-coded in source:
+
+```python
+from tangle_cli.pipelines import compile_pipeline_file
+
+compile_pipeline_file(
+    "pipeline.py",
+    "pipeline.yaml",
+    pipeline_annotations={"environment": "staging", "owner": "search-platform"},
+)
+```
+
+The same keyword exists on `tangle_cli.pipeline_compiler.compile_pipeline` and on `PipelineCompiler.compile_file`. There is no CLI flag: the source route already exists, and what the keyword adds is a programmatic/config route for the part of the block that varies by environment.
+
+Semantics:
+
+- **Per-key merge, caller wins.** `@pipeline(annotations={"author": "a", "version": "1.0"})` compiled with `pipeline_annotations={"version": "2.0", "environment": "staging"}` emits all three keys, with `version: "2.0"`. Source keys the caller does not mention are preserved, so invariants stay in source and only the varying subset is passed in.
+- **Omitted or `{}` is a no-op**, byte for byte — an empty mapping is not a destructive clear of the source block.
+- **Root only.** `subpipeline` children never inherit it, so child subgraph sidecar names, bytes, and component digests are unaffected. A child that wants annotations declares its own.
+- **Descriptive only.** Root metadata is not read by the orchestrator, so it cannot influence placement, routing, scheduling, or run identity. Use pipeline-run annotations for anything execution-bearing.
+- **`str -> str`, validated up front.** A non-mapping argument, a non-string key or value, an empty key, a `system/`-prefixed key (reserved by Tangle), or a template delimiter (`{{`, `{%`, `{#`) in a key or value raises `InvalidPipelineAnnotationsError` (a `CompileError`) before anything is imported or written. Annotations usually come from an untrusted config file, so the diagnostics name the key and the type and never echo a value. Values are baked into the compiled YAML and the stored pipeline definition: labels only, never secrets.
+
+The rules live in one place, `tangle_cli.schema_validation`: `check_annotations(mapping, policy=..., error_cls=...)` applied under a named `AnnotationPolicy`. `CALLER_ANNOTATION_POLICY` is the strict input policy described above; `DOCUMENT_ANNOTATION_POLICY` is the lenient policy every pipeline document is validated against (scalar-or-null values, no key rules), matching the schema and hand-authored YAML. Only the caller-supplied input surface is strict: existing documents are accepted exactly as before, and the document check still runs on the merged result, so annotations reaching the output by any route are validated.
+
+A distribution that reads these annotations from its own config file should call `check_annotations(mapping, policy=CALLER_ANNOTATION_POLICY, error_cls=...)` at config-parse time — passing its own error type and adding the config path and key to the message — so one user mistake produces one diagnostic instead of two competing ones. The compiler's own call is then the backstop for anything arriving by another route.
+
 ##### Conditional task execution
 
 Pipeline inputs used as conditions are ordinary `In[str]` values; there is no special conditional input annotation. Pass the value through the reserved task-call metadata keyword `is_enabled=`:

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/packages/tangle-cli/src/tangle_cli/__init__.py

@@ -14,6 +14,6 @@ from tangle_cli.dynamic_discovery_client import TangleDynamicDiscoveryClient
 try:
     __version__ = metadata_version("tangle-cli")
 except PackageNotFoundError:
-    __version__ = "0.1.17"
+    __version__ = "0.1.19"
 
 __all__ = ["TangleDynamicDiscoveryClient", "__version__"]

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/packages/tangle-cli/src/tangle_cli/pipeline_compiler.py

@@ -65,14 +65,19 @@ from .python_pipeline.compiler_context import (
     overrides_fingerprint,
 )
 from .python_pipeline.emit import _TASK_URL_PLACEHOLDER, emit_pipeline
-from .python_pipeline.errors import CompileError
+from .python_pipeline.errors import CompileError, InvalidPipelineAnnotationsError
 from .python_pipeline.pipeline import PipelineFn
 from .python_pipeline.ref import CallableRef
 from .python_pipeline.registered import _REGISTERED_URL_PLACEHOLDER
 from .python_pipeline.subpipeline import _SUBPIPELINE_URL_PLACEHOLDER, SubpipelineRef
 from .python_pipeline.trace import trace_pipeline
 from .python_pipeline.types import In
-from .schema_validation import SchemaValidationError, validate_dehydrated_pipeline
+from .schema_validation import (
+    CALLER_ANNOTATION_POLICY,
+    SchemaValidationError,
+    check_annotations,
+    validate_dehydrated_pipeline,
+)
 from .utils import dump_yaml
 
 
@@ -141,6 +146,7 @@ def compile_pipeline(
     pipeline_name: str | None = None,
     emit_components_sidecar: bool = True,
     image_overrides: Mapping[str, str] | None = None,
+    pipeline_annotations: Mapping[str, str] | None = None,
 ) -> CompileResult:
     """Compile ``script`` to a single pipeline YAML at ``output``.
 
@@ -174,6 +180,18 @@ def compile_pipeline(
         image_overrides: Compile-time image-id overrides from ``--image
             ID=REF``. They apply only to ``@task(image_id=...)`` refs that do
             not also set an explicit ``image=``.
+        pipeline_annotations: Caller-supplied ROOT ``metadata.annotations``
+            (``str -> str``), typically read from a downstream config file so
+            the block can vary per environment. Merged PER KEY over the root
+            ``@pipeline(annotations=...)`` block, caller winning on collision;
+            ``None`` / ``{}`` is a no-op that leaves the compiled bytes
+            identical. ROOT ONLY — ``subpipeline`` children do not inherit it,
+            so their sidecar names, bytes, and digests are unaffected. Root
+            metadata is descriptive: it is not read by the orchestrator and
+            cannot influence placement, routing, scheduling, or identity. See
+            :data:`tangle_cli.schema_validation.CALLER_ANNOTATION_POLICY`
+            for the accepted shape; a malformed mapping raises
+            :class:`~tangle_cli.python_pipeline.errors.InvalidPipelineAnnotationsError`.
 
     Returns:
         A :class:`CompileResult`. ``components_path`` is the sidecar path
@@ -186,6 +204,15 @@ def compile_pipeline(
     """
     overrides = dict(overrides or {})
     image_overrides = dict(image_overrides or {})
+    # Validated up front, by the shared validation layer, so a hostile or
+    # malformed annotation mapping fails before any module is imported or any
+    # file is written. The compiler owns no annotation rules of its own; it
+    # only chooses the caller-facing error type.
+    root_annotations = check_annotations(
+        pipeline_annotations,
+        policy=CALLER_ANNOTATION_POLICY,
+        error_cls=InvalidPipelineAnnotationsError,
+    )
 
     # 1. Validate the script path.
     script_path = Path(script).resolve()
@@ -241,6 +268,7 @@ def compile_pipeline(
             emit_components_sidecar=emit_components_sidecar,
             source_dirs=purge_dirs,
             image_overrides=image_overrides,
+            pipeline_annotations=root_annotations,
         )
 
         # 5. Compile the root (and, recursively, all children) into in-memory
@@ -445,6 +473,12 @@ def _compile_pipeline_fn(
     #    output guard must skip for THIS artifact's body.
     with _temp_sys_path(base_dir):
         builder = trace_pipeline(pipeline_fn, cfg=cfg, inputs={})
+    # Caller-supplied root annotations: ROOT ONLY (a child keeps exactly what
+    # its own ``@pipeline`` declared), merged PER KEY with the caller winning
+    # on collision, before emit so they pass the same emit-time guards as
+    # authored ones. ``update`` keeps the emitted order source-first.
+    if is_root and ctx.pipeline_annotations:
+        builder.annotations.update(ctx.pipeline_annotations)
     body_dict, exempt_paths = emit_pipeline(builder)
 
     # 3. The canonical compile key for dedup / cycle detection. A child is
@@ -2785,6 +2819,7 @@ class PipelineCompiler(TangleCliHandler):
         pipeline_name: str | None = None,
         emit_components_sidecar: bool = True,
         image_overrides: Mapping[str, str] | None = None,
+        pipeline_annotations: Mapping[str, str] | None = None,
     ) -> CompileResult:
         """Compile ``script`` to a single dehydrated pipeline YAML at ``output``.
 
@@ -2804,6 +2839,7 @@ class PipelineCompiler(TangleCliHandler):
             pipeline_name=pipeline_name,
             emit_components_sidecar=emit_components_sidecar,
             image_overrides=image_overrides,
+            pipeline_annotations=pipeline_annotations,
         )
         self.log.info(f"wrote {result.pipeline_path}")
         if result.components_path is not None:

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/packages/tangle-cli/src/tangle_cli/pipelines.py

@@ -259,6 +259,7 @@ def compile_pipeline_file(
     pipeline_name: str | None = None,
     emit_components_sidecar: bool = True,
     image_overrides: Mapping[str, str] | None = None,
+    pipeline_annotations: Mapping[str, str] | None = None,
     logger: Any | None = None,
 ) -> CompileResult:
     """Compile a Python-authored pipeline to a dehydrated YAML bundle.
@@ -271,6 +272,12 @@ def compile_pipeline_file(
     The :class:`~tangle_cli.pipeline_compiler.CompileResult` is returned as-is —
     unlike hydrate, the compiler already exposes its public result type, so there
     is nothing to repackage.
+
+    ``pipeline_annotations`` supplies ROOT ``metadata.annotations`` (``str ->
+    str``) merged per key over the root ``@pipeline(annotations=...)`` block,
+    caller winning on collision; it applies to the root only and is a no-op
+    when omitted or empty. See
+    :func:`~tangle_cli.pipeline_compiler.compile_pipeline`.
     """
 
     from .pipeline_compiler import PipelineCompiler
@@ -286,6 +293,10 @@ def compile_pipeline_file(
             pipeline_name=pipeline_name,
             emit_components_sidecar=emit_components_sidecar,
             image_overrides=dict(image_overrides) if image_overrides else None,
+            # Passed through unconverted: the compiler validates the shape and
+            # takes its own copy, so a malformed mapping fails with the
+            # compiler's value-free CompileError instead of a bare TypeError.
+            pipeline_annotations=pipeline_annotations,
         )
     except (CompileError, SchemaValidationError) as exc:
         raise PipelineValidationError(str(exc)) from exc

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/packages/tangle-cli/src/tangle_cli/python_pipeline/compiler_context.py

@@ -253,6 +253,14 @@ class CompileContext:
     root_overrides: dict[str, str] = field(default_factory=dict)
     emit_components_sidecar: bool = True
     image_overrides: dict[str, str] = field(default_factory=dict)
+    # Caller-supplied ROOT ``metadata.annotations`` (already validated),
+    # merged PER KEY over the root ``@pipeline(annotations=...)`` block just
+    # before emit. ROOT ONLY: children never inherit it, so a child sidecar's
+    # bytes — and therefore its component digest — are untouched by it. It is
+    # deliberately absent from :class:`PipelineCompileKey` /
+    # ``overrides_fingerprint`` (as ``image_overrides`` is), so sidecar
+    # filenames stay identity-derived rather than content-derived.
+    pipeline_annotations: dict[str, str] = field(default_factory=dict)
     max_depth: int = 32
     # Compiled CHILD artifacts keyed by compile key (Decision M dedup).
     # The root is NOT stored here; it is returned directly.

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/packages/tangle-cli/src/tangle_cli/python_pipeline/errors.py

@@ -27,3 +27,14 @@ class AmbiguousTaskIdError(CompileError):
 
 class InvalidArgumentTypeError(CompileError):
     """Raised on an argument value with no supported emit dispatch."""
+
+
+class InvalidPipelineAnnotationsError(CompileError):
+    """Raised on a malformed caller-supplied ``pipeline_annotations`` mapping.
+
+    A dedicated type because these annotations usually originate in a
+    downstream CONFIG file: a caller that reads such a file can catch this
+    precisely and re-raise with the config path and key attached, without
+    broadly catching :class:`CompileError` and swallowing unrelated compile
+    failures. Messages never echo an annotation value.
+    """

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/packages/tangle-cli/src/tangle_cli/python_pipeline/task_env.py

@@ -36,10 +36,65 @@ from __future__ import annotations
 import inspect
 from dataclasses import dataclass
 from pathlib import Path
+from types import FrameType
 from typing import TypeVar
 
 _TaskEnvT = TypeVar("_TaskEnvT", bound="TaskEnv")
 
+#: A dataclass-generated ``__init__`` is compiled by ``exec``, so its code
+#: object carries this synthetic filename instead of a real module path.
+_GENERATED_CODE_FILENAME = "<string>"
+
+#: Hard bound on the frame walk below. Construction of one object never needs
+#: this many frames; the bound only keeps a pathological stack from being
+#: walked to its root, degrading to the documented working-directory fallback.
+_MAX_CONSTRUCTION_FRAMES = 64
+
+
+def _definition_site_file(instance: object) -> str | None:
+    """``__file__`` of the code that constructed ``instance``, or ``None``.
+
+    The definition site is the first frame *outside* the construction of this
+    object: the frame after the OUTERMOST construction frame, which is
+    normally the dataclass-generated ``__init__``. Because the boundary is
+    found by identity and not by a fixed ``f_back`` count, the answer is the
+    author's file at any dataclass subclass depth — a subclass that overrides
+    ``__post_init__`` and calls ``super()`` adds a frame, and adding frames no
+    longer changes the result. ``None`` means the site has no ``__file__``
+    (``exec``'d or interactive code), which callers treat as "unknown".
+    """
+
+    frames: list[FrameType] = []
+    frame = inspect.currentframe()
+    try:
+        # Skip this helper itself, then collect the stack above it.
+        frame = frame.f_back if frame is not None else None
+        while frame is not None and len(frames) < _MAX_CONSTRUCTION_FRAMES:
+            frames.append(frame)
+            frame = frame.f_back
+    finally:
+        # Break the frame reference cycle this function would otherwise leave.
+        del frame
+
+    try:
+        outermost = -1
+        for index, candidate in enumerate(frames):
+            # A frame constructing THIS object binds it to ``self``: the base
+            # and every subclass ``__post_init__``, plus the generated
+            # ``__init__``. Nothing outside the construction can hold the
+            # object yet, so this is exact rather than a frame count.
+            code = candidate.f_code
+            if candidate.f_locals.get("self") is instance or (
+                code.co_name == "__init__"
+                and code.co_filename == _GENERATED_CODE_FILENAME
+            ):
+                outermost = index
+        site = frames[outermost + 1] if outermost + 1 < len(frames) else None
+        filename = site.f_globals.get("__file__") if site is not None else None
+        return filename if isinstance(filename, str) and filename else None
+    finally:
+        del frames
+
 
 @dataclass(frozen=True)
 class TaskEnv:
@@ -49,7 +104,8 @@ class TaskEnv:
         image: Container image for the component. Required.
         dependencies_from: Optional path to a ``pyproject.toml`` (or any file
             the hydrator understands) declaring pip dependencies. A relative
-            path is resolved at the ``TaskEnv`` *definition site*, so a shared
+            path is resolved at the ``TaskEnv`` *definition site* — the file
+            that constructed this env, at any subclass depth — so a shared
             ``_envs.py`` resolves intuitively; pass an absolute ``Path`` to
             avoid that. When omitted, the hydrator's existing dependency
             discovery still applies.
@@ -66,16 +122,11 @@ class TaskEnv:
 
         p = Path(self.dependencies_from)
         if not p.is_absolute():
-            # Frames: __post_init__ -> generated __init__ -> the definition site.
-            frame = inspect.currentframe()
-            caller = (
-                frame.f_back.f_back
-                if frame and frame.f_back and frame.f_back.f_back
-                else None
-            )
-            filename = caller.f_globals.get("__file__") if caller else None
-            caller_dir = Path(filename).resolve().parent if filename else Path.cwd()
-            p = caller_dir / p
+            filename = _definition_site_file(self)
+            # Working directory only as a last resort: the construction site
+            # has no file at all (exec'd or interactive code).
+            anchor = Path(filename).resolve().parent if filename else Path.cwd()
+            p = anchor / p
         # Frozen dataclass: bypass __setattr__ to store the resolved Path.
         object.__setattr__(self, "dependencies_from", p.resolve())
 

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/packages/tangle-cli/src/tangle_cli/schema_validation.py

@@ -25,6 +25,12 @@ Public surface:
   ``taskOutput.taskId``, undeclared ``graphInput.inputName``,
   ``outputValues`` ↔ ``outputs`` correspondence, scalar metadata
   annotations, pure componentRefs) and the no-template-delimiter scan.
+* :func:`check_annotations` plus :data:`DOCUMENT_ANNOTATION_POLICY` /
+  :data:`CALLER_ANNOTATION_POLICY` — the ONE place that says what a
+  ``metadata.annotations`` mapping may contain. Both the lenient check
+  applied to every pipeline DOCUMENT and the strict check applied to a
+  caller/config-supplied mapping are the same function under different
+  policies, so the two can never drift apart.
 
 Everything here is standalone — it never changes ``PipelineHydrator``
 behavior. ``compile_pipeline`` uses :func:`validate_dehydrated_pipeline`
@@ -34,6 +40,7 @@ from __future__ import annotations
 
 import json
 from collections.abc import Collection, Iterator, Mapping
+from dataclasses import dataclass
 from functools import lru_cache
 from pathlib import Path
 from typing import Any
@@ -195,6 +202,152 @@ def assert_no_template_delimiters(
     )
 
 
+# ---------------------------------------------------------------------------
+# Annotation policy: the one definition of what an annotations mapping may
+# contain, applied at two documented strictness levels.
+
+#: Annotation-key prefix Tangle reserves for its own annotations.
+RESERVED_ANNOTATION_KEY_PREFIX = "system/"
+
+
+@dataclass(frozen=True)
+class AnnotationPolicy:
+    """Which rules :func:`check_annotations` applies, and how it names the
+    mapping in diagnostics (``label``).
+
+    Every flag defaults to off, so a policy opts IN to strictness. With
+    ``require_string_values`` off, values fall back to the legacy
+    scalar-or-null rule rather than being unchecked.
+    """
+
+    label: str
+    require_string_values: bool = False
+    require_string_keys: bool = False
+    require_non_empty_keys: bool = False
+    reject_reserved_key_prefix: bool = False
+    reject_template_delimiters: bool = False
+    reject_non_mapping: bool = False
+
+
+#: Applied to every pipeline document validated by
+#: :func:`validate_dehydrated_pipeline`. Deliberately lenient: hand-authored
+#: and legacy YAML reaches this path, and any flag enabled here would reject
+#: documents that compile and run today.
+DOCUMENT_ANNOTATION_POLICY = AnnotationPolicy(label="metadata.annotations")
+
+#: Applied to a caller/config-supplied root annotations mapping (the
+#: ``pipeline_annotations`` compile argument, and any downstream config reader
+#: that wants to refuse a bad mapping early with its own file/key provenance:
+#: ``check_annotations(mapping, policy=CALLER_ANNOTATION_POLICY,
+#: error_cls=...)``). Strict ``str -> str`` because that input surface is new,
+#: has no legacy, and is usually an untrusted config file — hence also
+#: :func:`check_annotations`'s rule that a diagnostic names the key and the
+#: type or delimiter but never echoes a value. ``None`` / ``{}`` means nothing
+#: supplied and is a no-op, not a clear. ``reject_template_delimiters`` adds no
+#: rule the output lacks — :func:`assert_no_template_delimiters` scans the
+#: compiled output regardless; it moves the failure earlier, onto a message
+#: that names the offending annotation key.
+CALLER_ANNOTATION_POLICY = AnnotationPolicy(
+    label="pipeline_annotations",
+    require_string_values=True,
+    require_string_keys=True,
+    require_non_empty_keys=True,
+    reject_reserved_key_prefix=True,
+    reject_template_delimiters=True,
+    reject_non_mapping=True,
+)
+
+
+def check_annotations(
+    annotations: Any,
+    *,
+    policy: AnnotationPolicy,
+    error_cls: type[Exception] = SchemaValidationError,
+) -> dict[Any, Any]:
+    """Check an annotations mapping against ``policy`` and copy it.
+
+    Annotations are frequently UNTRUSTED input (a config file, a checked-in
+    YAML document), so every diagnostic names the offending KEY and the
+    offending TYPE or delimiter and NEVER echoes a value.
+
+    Args:
+        annotations: The mapping to check. ``None`` means "nothing supplied"
+            and is always accepted.
+        policy: Which rules apply — :data:`DOCUMENT_ANNOTATION_POLICY` or
+            :data:`CALLER_ANNOTATION_POLICY`.
+        error_cls: Exception type to raise, so a caller-input path can raise
+            its own precise type (``InvalidPipelineAnnotationsError``) while
+            the document path keeps raising
+            :class:`SchemaValidationError`. This module deliberately does
+            not import the authoring-layer error hierarchy.
+
+    Returns:
+        A plain ``dict`` copy in the caller's key order (empty for ``None``),
+        so later mutation of the supplied mapping cannot reach the compile.
+        No value is coerced or normalized — this function only accepts or
+        rejects.
+
+    Raises:
+        error_cls: on the first violation found.
+    """
+    if annotations is None:
+        return {}
+    if not isinstance(annotations, Mapping):
+        if not policy.reject_non_mapping:
+            return {}
+        raise error_cls(
+            f"{policy.label} must be a mapping of string keys to string "
+            f"values; got {type(annotations).__name__}."
+        )
+
+    checked: dict[Any, Any] = {}
+    for key, value in annotations.items():
+        if policy.require_string_keys and not isinstance(key, str):
+            raise error_cls(
+                f"{policy.label} keys must be strings; got a key of type "
+                f"{type(key).__name__}."
+            )
+        if policy.require_non_empty_keys and key == "":
+            raise error_cls(f"{policy.label} keys must not be empty.")
+        if policy.require_string_values:
+            # Report the type only — a rejected value may be untrusted.
+            if not isinstance(value, str):
+                raise error_cls(
+                    f"{policy.label} value for key {key!r} must be a string; "
+                    f"got {type(value).__name__}."
+                )
+        # bool is a subclass of int, so it is covered by int.
+        elif not (value is None or isinstance(value, (str, int, float))):
+            raise error_cls(
+                f"{policy.label}[{key!r}] must be a scalar (str/number/bool) "
+                f"or null, got {type(value).__name__!r}."
+            )
+        if policy.reject_reserved_key_prefix and isinstance(key, str):
+            if key.startswith(RESERVED_ANNOTATION_KEY_PREFIX):
+                raise error_cls(
+                    f"{policy.label} key {key!r} uses the reserved "
+                    f"{RESERVED_ANNOTATION_KEY_PREFIX!r} prefix, which Tangle "
+                    "keeps for its own annotations. Choose a different key."
+                )
+        if policy.reject_template_delimiters:
+            # Scanned with the SAME tokens the compiled-output guard uses, so
+            # an input check and the output contract can never disagree.
+            for where, text in ((f"key {key!r}", key), (f"value for key {key!r}", value)):
+                if not isinstance(text, str):
+                    continue
+                delim = next((d for _p, d in iter_template_delimiters(text)), None)
+                if delim is None:
+                    continue
+                raise error_cls(
+                    f"{policy.label} {where} contains the template delimiter "
+                    f"{delim!r}. Annotations are literal metadata written "
+                    "verbatim into the compiled pipeline, which must be fully "
+                    "rendered — resolve the template before passing the value."
+                )
+        checked[key] = value
+    return checked
+
+
 # ---------------------------------------------------------------------------
 # Phase 5: dehydrated-pipeline shape detection + semantic validation.
 #
@@ -411,15 +564,12 @@ def _validate_semantics(data: Mapping[str, Any]) -> None:
     metadata = data.get("metadata")
     if isinstance(metadata, Mapping):
         annotations = metadata.get("annotations")
+        # A non-mapping ``annotations`` is left to JSON-Schema, exactly as
+        # before. Everything a DOCUMENT's annotations may contain is decided
+        # by the shared policy below, so this backstop and the strict
+        # caller-input check can never disagree about a shared rule.
         if isinstance(annotations, Mapping):
-            for key, value in annotations.items():
-                # bool is a subclass of int, so it is covered by int.
-                if not (value is None or isinstance(value, (str, int, float))):
-                    raise SchemaValidationError(
-                        f"metadata.annotations[{key!r}] must be a scalar "
-                        f"(str/number/bool) or null, got "
-                        f"{type(value).__name__!r}."
-                    )
+            check_annotations(annotations, policy=DOCUMENT_ANNOTATION_POLICY)
 
 
 def validate_dehydrated_pipeline(

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tangle-cli"
-version = "0.1.17"
+version = "0.1.19"
 description = "CLI for Tangle, the open-source ML pipeline orchestration platform"
 readme = "README.md"
 requires-python = ">=3.10"

{tangle_cli-0.1.17 → tangle_cli-0.1.19}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "tangle-cli"
-version = "0.1.17"
+version = "0.1.19"
 description = "CLI for Tangle, the open-source ML pipeline orchestration platform"
 readme = "README.md"
 authors = [