RFC-0002: publish pipeline contract

Version: 0.2.1 | Status: normative | Phase: impl

1. Summary

[RFC-0002:C-SUMMARY] Summary (Informative)

RFC-0002 defines the normative contract for typub’s publish pipeline, grounded in product intent from RFC-0001.

This RFC specifies:

• The required pipeline stages and their ordering.
• The contract between shared pipeline logic and platform adapters.
• Failure handling and status persistence semantics during publish.

This RFC does not define platform-specific API details. Those belong to adapter-specific RFCs/ADRs. Update and republish semantics are out of scope for this draft and will be defined in a follow-up RFC.

Since: v0.1.0

2. Specification

[RFC-0002:C-PIPELINE-STAGES] Pipeline Stages (Normative)

The publish operation MUST execute in this logical order:

1. Resolve: Resolve content input and metadata.
2. Render: Render source content (Typst/Markdown) into HTML string.
3. Parse: Parse rendered content into a semantic document IR root (Document) rather than a bare node vector.
4. Transform: Apply shared, adapter-agnostic transformations on semantic IR.
5. Specialize: Perform adapter-specific payload planning, including collecting pending asset references and adapter metadata. This stage MUST NOT serialize IR to final target output and SHOULD avoid remote side effects.
6. Provision: Find or create remote target identity when required by the target API. This stage is OPTIONAL when publish can resolve identity atomically.
7. Materialize: Resolve asset references required by selected asset strategy. This stage MUST operate on the document asset index and/or specialization context, and MUST NOT require placeholder string replacement. This stage MAY use provision context from Stage 6. This stage is OPTIONAL when no remote asset materialization is needed.
8. Serialize: Convert resolved semantic IR to target output format (for example Markdown, Confluence storage format, Notion blocks). This is the first stage producing final output payload.
9. Publish: Execute adapter publish operation using serialized payload.
10. Persist: Persist successful publish result into status tracking.

IR preservation principle: Stages 3 through 7 MUST operate on typed semantic IR. Final target serialization MUST NOT occur before Stage 8.

Rationale: Delaying serialization until after materialization avoids placeholder-collision classes of bugs and preserves type-safe transformations.

Implementation MAY combine adjacent stages internally, and MAY use different intermediate representations across adapter families, but externally observable behavior (side effects and error propagation) MUST be equivalent to this order.

A stage MUST NOT mutate source content files.

Since: v0.1.0

[RFC-0002:C-ADAPTER-BOUNDARY] Adapter Boundary Contract (Normative)

For this RFC, an adapter is the platform-specific integration component that translates shared pipeline output into target-specific publish API requests and responses.

Each adapter implementation MUST declare:

• required input/output format expectations,
• asset strategy behavior,
• capability surface (for example tags/categories/internal-links support),
• unsupported behavior per capability gap (warn+degrade or hard error).

Capability declarations SHOULD be available in a machine-readable or centrally documented form.

Shared pipeline logic MUST remain platform-agnostic where practical. Adapter code MUST encapsulate platform-specific API calls and target-specific output shaping.

An adapter MUST NOT bypass status tracking writes on successful publish.

Since: v0.1.0

[RFC-0002:C-FAILURE-SEMANTICS] Failure and Status Semantics (Normative)

For this RFC, post+platform key means (post slug, platform name), where platform name is the adapter identifier.

If any stage before adapter publish fails, the operation MUST terminate without recording a successful publish result.

If adapter publish fails, the operation MUST surface an error and MUST NOT mark content as published in status tracking.

A successful publish record MUST, at minimum, persist published=true and published_at for the post+platform key. When provided by the target platform, platform-specific identifier MUST be persisted. URL MAY be absent.

Status persistence for a successful publish MUST be atomic at the local storage layer (for example, a single database transaction or crash-safe single-file replace), so a partial successful record is not observable.

If status persistence fails after adapter publish succeeds, the operation MUST be surfaced to the caller as a failure and MUST include reconciliation guidance to recover local status for the already-published remote state.

Retry behavior MAY be implemented by callers, but retries MUST preserve idempotent status semantics (no duplicate successful entries for one final published state).

Since: v0.1.0

Changelog

v0.2.1 (2026-02-21)

Terminology alignment with semantic IR

Added

• Update C-PIPELINE-STAGES to Document-root semantic IR and asset-index materialization language

v0.2.0 (2026-02-11)

Add Stage 5 (Provision) to the pipeline

Added

• Add Provision stage between Finalize and Materialize for remote target identity resolution
• Renumber Materialize to Stage 6, Publish to Stage 7, Persist to Stage 8

v0.1.0 (2026-02-11)

Initial draft