feat: introduce versioning and family support

[niteshpurohit]

• Added support for defining workflows with explicit versions and families.
• Updated the workflow definition DSL to accept workflow_family, workflow_version, and default_version parameters.
• Enhanced the Catalog class to manage definitions by family and version, allowing for version-specific fetching and resolution.
• Introduced new methods to fetch and resolve workflow definitions based on family and version.
• Updated ChildWorkflowSnapshot to include parent and child workflow family and version attributes.
• Enhanced tests to cover new versioning features, ensuring correct behavior for multiple versions within the same family.
• Updated documentation to reflect changes in workflow versioning and coexistence during cutover.

closes: #353

[Copilot]

Pull request overview

Introduces explicit workflow versioning and family identity across the core/karya workflow definition DSL, catalog resolution, and persisted snapshots, enabling safe coexistence and operator-visible cutovers as described in issue #353.

Changes:

• Extend Karya::Workflow.define and Karya::Workflow::Definition with workflow_family, workflow_version, and default_version metadata.
• Enhance Karya::Workflow::Catalog to group definitions by family/version and resolve a family’s default definition.
• Persist and surface family/version in workflow snapshots (including child workflow relationships) and update docs/specs to cover the new semantics.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/pages/workflows/versioning.md	Adds conceptual model and rules for workflow identity (family/version/id) and safe evolution.
docs/pages/workflows/replay.md	Clarifies replay remains bound to the version captured by the batch.
docs/pages/governance/rollout.md	Documents rollout semantics around default versions vs persisted batches.
docs/pages/adoption/cutover-rollback.md	Documents coexistence windows during workflow cutover/rollback.
core/karya/spec/karya/workflow_spec.rb	Updates DSL expectations and adds catalog resolve coverage.
core/karya/spec/karya/workflow/snapshot_spec.rb	Adds snapshot assertions for workflow family/version.
core/karya/spec/karya/workflow/definition_spec.rb	Covers new definition metadata and validates default_version boolean.
core/karya/spec/karya/workflow/child_workflow_snapshot_spec.rb	Verifies parent/child family+version identity is normalized and exposed.
core/karya/spec/karya/workflow/catalog_spec.rb	Adds coverage for versioned families, defaults, and duplicate version/default validation.
core/karya/spec/karya/queue_store/in_memory_workflow_validation_spec.rb	Adds regression coverage ensuring persisted runs remain bound to their resolved version.
core/karya/sig/karya/workflow.rbs	Extends signatures for define/definition/catalog/snapshots to include family/version metadata.
core/karya/sig/karya/queue_store/in_memory/internal/store_state.rbs	Adds family/version fields to stored workflow and child relationship registrations.
core/karya/sig/karya.rbs	Introduces a new type alias related to default-version flags.
core/karya/lib/karya/workflow/snapshot.rb	Adds workflow family/version to snapshot identity and readers, with normalization defaults.
core/karya/lib/karya/workflow/definition.rb	Stores normalized family/version and default-version flag on definitions.
core/karya/lib/karya/workflow/child_workflow_snapshot.rb	Extends child snapshot identity with family/version for parent and child sides.
core/karya/lib/karya/workflow/catalog.rb	Implements family/version indexing, fetch_version, and resolve APIs.
core/karya/lib/karya/workflow.rb	Extends the workflow DSL entrypoint and builder to accept family/version/default metadata.
core/karya/lib/karya/queue_store/in_memory/internal/workflow_support.rb	Persists family/version into workflow registrations and emitted snapshots during enqueue/snapshot building.
core/karya/lib/karya/queue_store/in_memory/internal/workflow_child_state.rb	Includes family/version when building snapshots for child workflow state.
core/karya/lib/karya/queue_store/in_memory/internal/store_state_workflow_registration.rb	Adds stored workflow registration fields for family/version with defaults.
core/karya/lib/karya/queue_store/in_memory/internal/store_state.rb	Adds family/version to stored child relationships and workflow registration defaults.
core/karya/lib/karya/queue_store/in_memory/internal/child_workflow_support.rb	Propagates family/version identity into child workflow registrations and relationships.

[Copilot]

Pull request overview

Introduces explicit workflow family + version metadata across the workflow DSL, catalog resolution, and persisted snapshot surfaces, enabling safe coexistence and operator-visible cutovers for evolving workflows (issue #353).

Changes:

• Extend workflow definition DSL and Workflow::Definition to carry workflow_family, workflow_version, and default_version.
• Enhance Workflow::Catalog with family/version indexing plus resolve (default) and fetch_version (explicit) lookup APIs.
• Plumb family/version through in-memory queue store registrations and snapshots (workflow + child-workflow relationships), with supporting tests and docs.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/pages/workflows/versioning.md	Expands documentation for workflow identity (family/version) and safe evolution rules.
docs/pages/workflows/replay.md	Clarifies replay remains bound to the captured workflow version.
docs/pages/governance/rollout.md	Notes rollout semantics for workflow families and default versions.
docs/pages/adoption/cutover-rollback.md	Adds cutover guidance for version coexistence windows.
core/karya/spec/karya/workflow_spec.rb	Updates DSL expectations and adds Catalog#resolve coverage.
core/karya/spec/karya/workflow/snapshot_spec.rb	Verifies snapshot surfaces expose workflow family/version.
core/karya/spec/karya/workflow/definition_spec.rb	Adds definition metadata assertions and validates default_version type.
core/karya/spec/karya/workflow/child_workflow_snapshot_spec.rb	Adds parent/child family+version identity expectations.
core/karya/spec/karya/workflow/catalog_spec.rb	Adds family/version resolution tests and error cases for defaults/duplicates.
core/karya/spec/karya/queue_store/in_memory_workflow_validation_spec.rb	Ensures coexisting versions remain bound per batch snapshot identity.
core/karya/sig/karya/workflow.rbs	Updates RBS surface for new metadata and catalog APIs (needs corrections per comments).
core/karya/sig/karya/queue_store/in_memory/internal/workflow_support.rbs	Adds signatures for refactored enqueue registration payload wiring.
core/karya/sig/karya/queue_store/in_memory/internal/store_state.rbs	Extends registration/relationship signatures to include family/version.
core/karya/lib/karya/workflow/snapshot.rb	Adds workflow family/version to snapshot identity normalization and readers.
core/karya/lib/karya/workflow/definition.rb	Stores/normalizes family/version/default metadata and exposes default_version?.
core/karya/lib/karya/workflow/child_workflow_snapshot.rb	Adds explicit parent/child family/version identity and delegates via identity objects.
core/karya/lib/karya/workflow/catalog.rb	Implements family/version indexing plus resolve / fetch_version.
core/karya/lib/karya/workflow.rb	Extends Workflow.define DSL to accept family/version/default metadata.
core/karya/lib/karya/queue_store/in_memory/internal/workflow_support.rb	Plumbs family/version into stored workflow registrations and snapshots.
core/karya/lib/karya/queue_store/in_memory/internal/workflow_child_state.rb	Ensures child workflow snapshots include family/version.
core/karya/lib/karya/queue_store/in_memory/internal/store_state_workflow_registration.rb	Adds workflow family/version fields into stored registration struct.
core/karya/lib/karya/queue_store/in_memory/internal/store_state.rb	Extends workflow registrations and child relationships with family/version defaults.
core/karya/lib/karya/queue_store/in_memory/internal/child_workflow_support.rb	Propagates parent/child identity family/version during child workflow enqueue registration.

[Copilot]

Pull request overview

Introduces explicit workflow versioning semantics to Karya so operators and long-lived/persisted workflow batches remain bound to the workflow definition version chosen at submission time, while allowing multiple versions of the same workflow family to coexist during cutovers.

Changes:

• Extends the workflow DSL/definition model with workflow_family, workflow_version, and default_version, and updates snapshots to expose this identity.
• Enhances Karya::Workflow::Catalog to index definitions by family/version, resolve defaults per family, and fetch specific versions.
• Propagates family/version through the in-memory queue store’s workflow registrations and child-workflow relationship snapshots; updates docs and tests accordingly.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/pages/workflows/versioning.md	Expands workflow versioning documentation with identity model and safe evolution rules.
docs/pages/workflows/replay.md	Documents replay staying bound to the batch’s captured workflow version.
docs/pages/governance/rollout.md	Adds guidance about default version vs compatibility window for older versions.
docs/pages/adoption/cutover-rollback.md	Adds cutover/coexistence window guidance for durable workflows.
core/karya/lib/karya/workflow.rb	Extends .define DSL to accept family/version/default metadata and passes through builder.
core/karya/lib/karya/workflow/definition.rb	Adds normalized workflow_family, workflow_version, and default_version? to definitions.
core/karya/lib/karya/workflow/catalog.rb	Adds family/version indexing, default resolution, and version-specific fetch APIs.
core/karya/lib/karya/workflow/snapshot.rb	Adds workflow family/version to snapshot identity and attribute normalization.
core/karya/lib/karya/workflow/child_workflow_snapshot.rb	Adds parent/child workflow family/version identity to child relationship snapshots.
core/karya/lib/karya/queue_store/in_memory/internal/workflow_support.rb	Stores workflow family/version in workflow registrations and snapshot builders; refactors enqueue registration payload building.
core/karya/lib/karya/queue_store/in_memory/internal/workflow_child_state.rb	Includes workflow family/version when building workflow snapshots and child snapshots.
core/karya/lib/karya/queue_store/in_memory/internal/store_state.rb	Extends stored workflow registration + relationship metadata with family/version defaults.
core/karya/lib/karya/queue_store/in_memory/internal/store_state_workflow_registration.rb	Extends workflow registration struct to store family/version with defaults.
core/karya/lib/karya/queue_store/in_memory/internal/child_workflow_support.rb	Propagates parent/child family/version through child enqueue metadata/relationship registration.
core/karya/sig/karya/workflow.rbs	Mirrors new DSL keywords, definition/catalog APIs, and snapshot/child snapshot identity fields in RBS.
core/karya/sig/karya/queue_store/in_memory/internal/workflow_support.rbs	Adds signatures for new internal enqueue helpers and registration payload builder.
core/karya/sig/karya/queue_store/in_memory/internal/store_state.rbs	Updates store state workflow registration/relationship signatures to include family/version.
core/karya/sig/karya/queue_store/in_memory/internal/child_workflow_support.rbs	Updates child workflow support types to include parent family/version and helper constructor.
core/karya/spec/karya/workflow_spec.rb	Updates DSL expectations and catalog resolution coverage.
core/karya/spec/karya/workflow/definition_spec.rb	Adds definition metadata/default validation coverage.
core/karya/spec/karya/workflow/catalog_spec.rb	Adds family/version resolution, duplicate version/default rejection, and missing default/version error coverage.
core/karya/spec/karya/workflow/snapshot_spec.rb	Asserts snapshot exposes explicit family/version identity.
core/karya/spec/karya/workflow/child_workflow_snapshot_spec.rb	Asserts child relationship snapshots carry parent/child family/version identity.
core/karya/spec/karya/queue_store/in_memory_workflow_validation_spec.rb	Adds integration coverage ensuring batches remain bound to their resolved version while newer versions coexist.