validation-patterns

name	validation-patterns
description	Kailash validation — parameter, DataFlow, connection, workflow, security, marker scrubbing.

Kailash Validation Patterns

Validation patterns and compliance checking for Kailash SDK development.

Sub-File Index

Core Validations

• validate-parameters - Node parameter validation
  • Required params, type checking, value ranges, format, defaults
• validate-connections - Connection validation
  • 4-parameter format, node existence, param name matching, type compatibility, circular dependency detection
• validate-workflow-structure - Workflow validation
  • Node ID uniqueness, dead-end detection, entry/exit point validation

Framework-Specific Validations

• validate-dataflow-patterns - DataFlow compliance
  • Result access: results["node_id"]["result"] (not .result)
  • String ID preservation, multi-instance isolation, transaction patterns
• validate-absolute-imports - Import validation
  • Absolute vs relative, module path correctness, circular/missing import detection
• validate-security - Security checks
  • Secret exposure, SQL/code injection, file path traversal, API key handling

Codebase Hygiene Validations

• validate-codebase-hygiene-markers - Internal-tracker marker scrubbing + three-layer regex gate
  • 4-class disposition catalog (Class 1a banner / 1b docstring provenance / 2 active iterative / 3 cross-reference)
  • Three-layer hygiene gate (pre-commit hook + shared script + Tier-2 regression test)
  • Synthetic-PR validation protocol + multi-shard cleanup strategy + release-cycle integration
  • Authoring gotchas: YAML scalar fragility with embedded colons, grep -I for binary skip, \.egg-info/ exclusion shape
  • Origin: issue #781 (TODO-NNN cleanup, May 2026)
• orphan-audit-playbook - Orphan detection for facade/manager classes
  • Phase 5.11 evidence (2,407 LOC trust orphan); 5-step /redteam audit; sub-package collection-gate patterns; same-shard sweep §4a

Quick Reference

What Each Validation Catches

Validation	Catches	Key Pattern
Parameters	Missing/wrong-type params	Check before workflow.build()
Connections	Wrong 4-param format, nonexistent nodes	(src_id, src_param, tgt_id, tgt_param)
Workflow	Duplicate IDs, dead-ends, no entry point	Structural integrity
DataFlow	.result access, UUID conversion	results["id"]["result"]
Imports	Relative imports, circular deps	Absolute imports only
Security	Hardcoded secrets, SQL injection	Env vars, parameterized queries

Automated Validation

from kailash.validation import WorkflowValidator

validator = WorkflowValidator(workflow)
results = validator.validate_all()

if not results.is_valid:
    for error in results.errors:
        print(f"Error: {error}")

Pre-Execution Checklist

• All required parameters provided
• All connections use 4-parameter format
• No missing or duplicate node IDs
• Called .build() before execute
• Using correct runtime type

CI Integration

python -m kailash.validation.cli validate-all
python -m kailash.validation.cli check-security

End-to-End Pipeline Regression Above Unit/Integration

Some failure modes are invisible at Tier 1 unit and Tier 2 integration because each step in a multi-step pipeline works in isolation — the break is at the seam between steps. A pipeline like km.train(df) → km.register(result, name=...) can have 100% unit coverage on km.train AND 100% integration coverage on km.register while the chain fails because result is missing a field the next step needs (the "fake-integration" failure mode).

Defense: A release-blocking regression tier above Tier 3 — a test that executes the full pipeline against real infrastructure AND asserts a deterministic fingerprint over the output. Any change that alters observable behavior flips the fingerprint and blocks release.

Pattern

# DO — release-blocking regression with pinned SHA-256 fingerprint
@pytest.mark.regression
@pytest.mark.release_blocking
async def test_readme_quick_start_end_to_end(real_conn):
    # 1. Execute the README Quick Start verbatim
    result = await km.train(df, target="churned")
    registered = await km.register(result, name="demo")
    # 2. Compute fingerprint over deterministic output
    fingerprint = hashlib.sha256(
        json.dumps(registered.artifact_uris, sort_keys=True).encode()
    ).hexdigest()
    # 3. Assert against pinned value (pinned in spec)
    assert fingerprint == "c962060cf467cc732df355ec9e1212cfb0d7534a3eed4480b511adad5a9ceb00"

# DO NOT — rely on unit + integration alone
def test_km_train_unit(): ...        # passes, km.train works in isolation
def test_km_register_integration(): ... # passes, km.register works given a valid result
# Chain still breaks because result is missing `.trainable` back-reference.

When to apply

• Public multi-step pipelines documented in README / spec Quick Start sections
• Any chain where A() → B(A's output) → C(B's output) is the user's primary ergonomic
• Cross-package integration surfaces (kailash.ml facade → dataflow.ml → nexus.ml handoff)

Origin

Session 2026-04-23 kailash-ml 1.0.0 M1 W33b shard — regression test caught the km.train → km.register trainable-field gap (commit 15033fa6) that unit tests couldn't. Pinned fingerprint: specs/ml-engines-v2.md §16.3. See skills/34-kailash-ml/m1-release-wave.md § "Release-Blocking README Quick Start Regression".

Validation Rules

• Always validate parameters before execution, connections before building, security before deployment, imports before commit
• Never skip parameter validation, connection validation, security validation

Related Skills

• 17-gold-standards - Compliance standards
• 31-error-troubleshooting - Error troubleshooting
• 01-core-sdk - Core patterns
• 02-dataflow - DataFlow patterns

Support

• gold-standards-validator - Compliance checking
• pattern-expert - Pattern validation
• testing-specialist - Test validation