Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RFC-0003: update and republish semantics

Version: 0.1.0 | Status: normative | Phase: impl

1. Summary

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

RFC-0003 defines update and republish semantics for typub and complements RFC-0002.

This RFC specifies:

  • how the system decides create vs update for a post+platform key,
  • idempotency guarantees for repeated publish attempts,
  • conflict and retry behavior when remote state diverges,
  • status tracking requirements for successful republish outcomes.

This RFC does not define platform-specific API payload details. Adapter-specific mapping remains implementation-specific as long as it satisfies the normative behavior here.

Since: v0.1.0

2. Specification

[RFC-0003:C-DECISION-KEY] Create-vs-Update Decision Key (Normative)

The system MUST determine create-vs-update behavior per post+platform key, where post+platform key means (post slug, adapter identifier).

Decision order:

  1. If a previously published remote identifier exists in local status for the post+platform key, the publish attempt MUST execute as an update path using that identifier.
  2. If no remote identifier exists, the adapter MAY resolve an update target via a deterministic platform-native lookup key (for example slug, title, or database-specific key).
  3. Cached URL MAY be used only as a non-authoritative hint. Cached URL alone MUST NOT be treated as identity.
  4. If no update target is resolved, the publish attempt MAY proceed to create only after duplicate precheck according to RFC-0003:C-CONFLICTS.

The decision key semantics in this RFC MUST remain consistent with status semantics in RFC-0002:C-FAILURE-SEMANTICS.

Since: v0.1.0

[RFC-0003:C-IDEMPOTENCY] Republish Idempotency (Normative)

Repeated publish attempts for the same post+platform key and same logical content state MUST be idempotent from the perspective of local status and SHOULD avoid creating duplicate remote objects.

Requirements:

  • The system MUST maintain at most one final successful status record per post+platform key.
  • A retried attempt MUST update the existing status record instead of creating duplicate successful records.
  • Republish of changed content MAY result in a different remote revision/version, but local status MUST continue to represent one current successful published state for the key.
  • If a duplicate remote object cannot be avoided due to target-platform limitations, the adapter MUST surface reconciliation guidance and retain one canonical local status record.

Callers MAY retry failed operations, but retries MUST preserve these idempotent status semantics.

Since: v0.1.0

[RFC-0003:C-CONFLICTS] Conflict and Retry Policy (Normative)

When remote state diverges from local assumptions during update, the adapter MUST surface a conflict-class error unless a fallback-to-create path is explicitly supported by the adapter behavior and duplicate precheck passes.

Conflict examples include:

  • missing remote object for stored remote identifier,
  • remote version/precondition mismatch,
  • immutable-state rejection by target platform,
  • duplicate-create candidate detected during create precheck.

Duplicate-create rule:

  • If update target cannot be resolved and create precheck indicates an equivalent remote object already exists, the operation MUST fail with conflict-class error.
  • In this case, the adapter MUST NOT create a new remote object.

Retry policy:

  • Callers MAY retry transient failures.
  • Callers SHOULD NOT blindly retry deterministic conflict errors without changing local or remote state.
  • If fallback-to-create is used after update miss, the operation MUST be observable in logs as an update->create transition.

Since: v0.1.0

[RFC-0003:C-STATUS] Republish Status Semantics (Normative)

On successful create or update, status persistence MUST satisfy RFC-0002:C-FAILURE-SEMANTICS and additionally meet the following republish rules:

  • The persisted post+platform record MUST represent the latest successful publish outcome.
  • If a remote identifier changes because of update->create fallback, local status MUST be replaced with the new identifier atomically.
  • If remote publish succeeds but local status persistence fails, the operation MUST fail and MUST include reconciliation guidance consistent with RFC-0002:C-FAILURE-SEMANTICS.

A successful republish record MAY omit URL when target platform does not provide one.

Since: v0.1.0

Changelog

v0.1.0 (2026-02-11)

Initial draft