Catalog and Packaging

Catalog and Packaging defines the portable boundary between symbolic references in a Workfile and the exact content used to validate and execute it. Catalogs publish artifacts; deployments select artifacts and local files; resolution fixes those selections by version and digest.

A resolution is complete when every dependency reachable from the root Workfile has an exact identity and content digest, and no unresolved or conflicting reference remains. A conforming implementation can use a lock document or another internal representation; this specification constrains the resolution’s information and behavior, not its storage format.

Catalog Boundary

A catalog publishes immutable versions of connector manifests and filter packages under namespaces. For each published artifact it supplies the namespace, exact version, manifest document, all package files, and their digests.

Content published under one namespace and exact version MUST NOT change. Correcting that content requires a new version.

Catalog discovery, search, transport, authentication, mirroring, availability, trust policy, and version-selection algorithm are outside this specification. A deployment can use multiple catalogs or no networked catalog.

Regardless of source, equal namespace, version, and digest identify equal artifact content. A catalog does not publish deployment connections, credentials, deployment inputs, schema overlays, local Workfiles, or local template content.

Catalog content MUST NOT select a connection or grant a capability. A validator MUST treat manifests and filter packages as untrusted input and enforce their document formats before using their declarations.

Namespaces

A catalog namespace matches the catalog-namespace production in the Syntax Reference and identifies exactly one connector or one filter package within its artifact kind. Connector and filter namespaces occupy separate registries, so the same spelling can exist once in each without collision.

Within a kind, one namespace has one owner and MUST NOT be rebound to unrelated semantics across versions.

Canonical Namespaces

A canonical namespace is assigned by the applicable Connector Namespace Registry or Filter Package Namespace Registry to an artifact in the Standard Library. Its manifest, fixtures, and semantics are normative content of the corresponding Library edition.

An implementation MUST resolve a referenced canonical namespace only to that Standard Library artifact for the selected Library edition. An implementation performing resolution MUST NOT replace, shadow, or augment that canonical artifact.

Implementing a canonical connector remains optional unless a conformance claim or referenced Workfile requires it; its name and semantics are not optional.

Reserved Namespaces

A reserved namespace is held by this specification for syntax or future standard artifacts. It has no vendor owner and MUST NOT resolve from a catalog.

wf is reserved for constructs and capabilities defined by this specification and never identifies a connector or filter package. The namespace registries are the authoritative lists of canonical and reserved names.

Reserving a name is not a declaration that an artifact exists. A Workfile reference to a reserved namespace that has no defined artifact is invalid.

Vendor Namespaces

A vendor namespace is any valid namespace not canonical or reserved. Its publisher controls its artifacts and versions.

An implementation performing resolution MUST establish one unambiguous owner for the namespace and reject supplied catalog entries that identify distinct artifacts by the same kind, namespace, and exact version. Vendor namespaces have no semantics supplied by this specification beyond their resolved manifests.

Portability of a Workfile using one therefore requires access to an artifact with the same exact content and an implementation capable of realizing its contract. A private artifact follows the same rules as a publicly distributed one.

References and Versions

An action or trigger operation key references a connector by namespace and a member declared by its manifest. A dotted filter name similarly references a filter-package namespace and declared filter.

Action, trigger, and dotted filter references in a Workfile do not contain a version. Version constraints and exact pins are resolution inputs supplied by the deployment, project metadata, or an accepted lock representation; they are not expression values and do not alter operation-key syntax.

An exact artifact version is a complete SemVer 2.0.0 version, including prerelease and build metadata when present. A version constraint is deployment syntax outside this specification format.

Selection MUST apply SemVer precedence and the compatibility requirements of the applicable manifest format. It MUST NOT treat build metadata as precedence, but an exact pin with build metadata matches only that identity.

A selected artifact’s manifest namespace and version MUST equal the requested namespace and selected exact version. Unsuccessful selection and pin verification are classified under Resolution and Pinning.

During validation, activation, execution, replay, and continuation, an implementation MUST NOT silently substitute a resolved dependency, required capability, or pinned content identity.

Resolution and Pinning

The following table assigns resolution classifications and codes. A completed lookup with no result is distinct from resolution input that was not supplied. Absence of definition-owned content is established against supplied project-content input.

Condition	Classification and code
Required resolution input was not supplied	The dependent result is incomplete, as defined under Static Validation.
Supplied catalog resolution establishes no namespace owner, no artifact satisfying the constraints, or incompatible version constraints	Unsupported, deployment.dependency.
Selected or pinned artifact content is unavailable	Unsupported, deployment.dependency.
Supplied content does not match its recorded or requested digest	Unsupported, deployment.dependency; the mismatched content is not used.
A conforming selected manifest does not declare the referenced action, trigger, or filter	Invalid, document.reference.
Required project-local callee, template, schema, or other definition-owned content has not been selected or pinned and is absent from supplied project content	Invalid, dependency.unresolved.
Selected artifact violates its document format or a cross-document contract, including a malformed digest or a namespace/version inconsistent with its selected identity	Invalid, dependency.invalid.
Supplied catalog has conflicting namespace owners or distinct contents under one kind, namespace, and exact version	Invalid, dependency.invalid.

Unavailable or mismatched content prevents checks that depend on it; independent checks and known support failures are handled under Static Validation.

Resolution begins before resolution-dependent static validation and completes before trigger activation or run execution. It recursively identifies the root Workfile; every connector and filter package it references; applicable schema overlays; reachable templates and other project content; every wf.call callee and its dependencies; the Standard revision and any explicit format discriminator; and required time-zone data.

For each dependency, the resolution records its logical identity, exact version where versioned, and applicable document, file, or file-set digest. It also records the selected Standard revision and any declared Workfile format discriminator.

Connection identity participates in resolution as defined under Connection Selection, but credentials and field values MUST NOT enter the portable resolution. Static validation and execution MUST use the same resolved content.

Once a workflow’s triggers are activated or a run begins, changes to catalogs, source files, overlays, connection selection, or time-zone data MUST NOT alter that trigger activation or run. Credential refresh that preserves the selected connection’s contract does not change resolution.

A deployment MAY reuse one resolution for multiple runs, but every run MUST identify the resolution it used. When resolving or continuing from persisted resolution data, an implementation MUST refuse supplied content that no longer satisfies its pin before dispatching a new action. An implementation can continue with retained content that does satisfy the pin; continued catalog availability is not required. Missing pinned content and content whose digest differs are distinct resolution failures.

Resolver ordering, cache layout, lock-file syntax, and internal persistence are implementation-defined.

Connector Resolution

All action and trigger references to one connector namespace in a resolved workflow graph MUST select one exact connector version and manifest digest. The selected manifest MUST conform to Connector Manifests and declare every referenced member.

The selected manifest’s connector namespace and version are checked against the resolution entry as required under References and Versions. Connection selection and overlay selection occur after the manifest is fixed.

Connection resolution for each action and trigger is governed by Deployment Connections. The resolution records the connection identity and overlay digest, if any, for every producing or consuming position whose static type depends on them.

A connection change that affects fields, scopes, authentication, or overlay requires deployment revalidation even when the connector manifest is unchanged.

Filter Package Resolution

All filters using one package namespace in a resolved workflow graph MUST select one exact package version, manifest digest, and package file-set digest. The package MUST conform to Filter Package Manifests, declare every referenced filter, and pass its fixtures before validation relies on its signatures.

Evaluation uses the exact conforming package artifact fixed under Filter Package Resolution. Package data that can affect results is included as required under Built-in Filters and Standard Filter Packages.

A package implementation MUST NOT consult a newer manifest, fixture set, locale table, or other mutable resource while executing an older resolution.

Time Zone Data

Resolution records the exact IANA Time Zone Database release used for named-zone validation and time operations, using the database’s release identifier such as 2026a. A release is required whenever reachable syntax or a reachable resolved contract can consume an IANA name, including every reachable to_timezone call and every reachable trigger field that accepts a named zone; the requirement does not depend on the runtime value of a computed string.

Syntax and contracts restricted to fixed offsets do not require database lookup. Validation, execution, recovery, and re-evaluation MUST use the recorded release.

If it is unavailable, the resolved Workfile is unsupported; an implementation MUST NOT substitute its current database silently.

Referenced Workfiles and Project Content

A project-relative path names content belonging to the project. An implementation can store that content in a filesystem, database, archive, object store, or another representation.

The path does not give a running workflow access to the host filesystem. A referenced Workfile or other project entry is identified by a normalized project-relative path.

A reference MUST NOT be absolute or contain an empty, . or .. segment. Path comparison is by Unicode code-point sequence with / as separator and is case-sensitive regardless of how the content is stored.

Each wf.call target MUST end in .workfile and resolve statically to one Workfile document digest. A target with another extension is invalid with document.reference. Resolution recursively includes that Workfile’s catalog dependencies, overlays, project content, and callees. The .workfile extension is the prescribed portable extension for Workfile documents in project content; it does not constrain conformance-case filenames or non-project transport containers.

A cycle in the static call graph is invalid. Two references to the same normalized path within one resolution MUST identify the same digest.

Templates and other referenced entries are pinned by file digest. A referenced template set is pinned as the complete reachable file set under its path, including relative names; adding, removing, renaming, or changing a reachable entry changes the digest.

Resolution MUST reject missing content and a path collision after normalization. When project content is obtained from a filesystem, the implementation MUST ensure that symbolic links and equivalent indirections do not resolve outside the project boundary.

Digests

A digest has the form sha256: followed by 64 lowercase hexadecimal digits. It identifies bytes under one of the algorithms below.

Implementations MUST compare the complete string and MUST reject an unsupported algorithm rather than interpreting it as SHA-256.

Document Canonical Form

The document canonical form of a standard document is Canonical JSON Value Serialization of the serialization-layer value produced by the serialization rules. It is independent of contextual typing, validation, and resolution.

Comments, YAML presentation, quoting choice, and line endings do not contribute.

Extension keys and their values also contribute. A Serialization string remains a string in document canonical form even when contextual typing later interprets it as an enum member, timestamp, duration, expression-bearing value, or other declared type.

Document canonicalization MUST NOT perform contextual typing or validation, perform I/O, resolve references, omit defaulted fields that are present, or insert optional defaults absent from the parsed document. It canonicalizes one serialized document value; resolution identity is represented by the separately digested dependency set.

Document Digests

The document digest is sha256: followed by the lowercase SHA-256 digest of the UTF-8 bytes of its document canonical form. Workfiles, connector manifests, filter-package manifests, schema overlays, and other standard documents pinned by content use this rule.

Documents that differ only in mapping-entry order have the same document digest. A document digest is computed after successful parsing under the serialization rules and before contextual typing, resolution, or semantic validation.

A document that is structurally, contextually, or semantically invalid can therefore have a document digest; the digest identifies its serialized content and does not certify validity. Input that fails the serialization rules has no document digest.

Verification recomputes the digest from the supplied document and requires exact equality.

File Digests

The file digest is sha256: followed by the lowercase SHA-256 digest of the file’s exact bytes, with no newline, Unicode, text-encoding, or metadata normalization. File names, permissions, timestamps, and other filesystem metadata are not part of a file digest.

Manifest and Workfile documents use document digests when pinned as documents. The same bytes can therefore have a different file digest and document digest, because the latter ignores comments, YAML layout and collection style, quoting choices, line-ending representation, and mapping-entry order.

File-Set Digests

A file set is a finite map from normalized relative paths to file digests. The file-set digest is the document digest of that map. Paths use /, are case-sensitive, and MUST satisfy the project-content path restrictions.

Every entry that can affect artifact behavior MUST appear exactly once. Storage containers and storage metadata do not appear.

The filter-package file-set digest covers its manifest bytes, fixtures, immutable data, and any packaged implementation content. Where the manifest is included as a file, its file digest and its separately recorded document digest serve different purposes.

Verification MUST reject a missing, additional, renamed, or digest-mismatched entry.

Extensions and Forward Compatibility

The following extension-key rules apply to every standard document defined here.

A key beginning with x- in a standard-defined structural map is an extension key rather than an unknown key. An implementation MUST accept and preserve it through resolution, but MUST ignore it for standard validation and execution semantics.

An extension key’s value can be any value in the serialization subset. An extension key MUST NOT satisfy a required standard field, select an operation, change a type, or alter standard validation or execution semantics.

The extension-key rule does not reclassify user data. In an explicit wf.value, a compact value body with no operation, or another position expressly defined as data, an x- key is an ordinary data key.

In a step body that contains an operation, an adjacent x- key is an extension key and does not count as an operation or modifier.

An extension key MUST be preserved in document and file-set digests.

Any other unknown structural key is invalid under Duplicate and Unknown Keys. An implementation MUST NOT accept it on the theory that a later Standard version might define it.

A later Standard revision can add optional fields and artifacts while preserving the meaning of existing unversioned documents and documents in any explicitly versioned format it extends.

A document using a recognized optional addition is unsupported, rather than invalid, on an implementation that recognizes the document’s format but does not implement the Standard revision or capability that defines the addition. An unrecognized explicit format discriminator is unsupported.

Malformed use of a supported feature is invalid. An extension that needs portable semantics, affects validation or execution, or needs to be understood by another implementation requires a registered capability, profile, manifest version, or future Standard revision; an x- key alone cannot provide those semantics.