publication/artifacts/specifications/publication-model.md

Civic Infrastructure Publication Model

1. Purpose

This specification defines the common publication model used by Civic Infrastructure components.

Its purpose is to ensure that editable source material, public discussion, immutable publication, and publication history remain distinct while using the same vocabulary and conventions across services.

This model may be used by Hubzilla, Portal, and other Civic Infrastructure components that publish durable public artifacts.

2. Roles of the Systems

Gitea

Gitea is the authoritative source repository for publication artifacts.

It contains:

• editable drafts;
• revision history;
• approved source material;
• publication metadata;
• publication records.

Gitea is where a future revision is edited and tracked before publication.

IPFS

IPFS is the immutable publication layer.

A published artifact placed on IPFS is identified by its CID.

Published content is not modified in place. A changed artifact is published as a new object with a new CID.

Human-Facing Service

A service such as Hubzilla or Portal may present the current published artifact to users.

The service may provide:

• readable presentation;
• explanation;
• discussion;
• comments;
• links;
• the current CID;
• the current publication metadata.

The human-facing representation is not itself the authoritative immutable publication unless it is the exact object identified by the published CID.

3. Defined Terms

Draft

A Draft is an editable artifact that has not yet been published as the current authoritative version.

A Draft:

• lives in Gitea;
• may change;
• may accumulate Git history;
• may be reviewed and discussed;
• does not yet have a publication CID.

A Draft may identify the Published Version from which it descends.

Published Version

A Published Version is the exact approved byte sequence released as an authoritative Civic Infrastructure artifact.

A Published Version:

• is no longer edited in place;
• has a Civic SHA-256 value;
• has an IPFS CID;
• has an associated Publication Record;
• remains part of the permanent publication history after replacement.

SHA-256

The SHA-256 value is the Civic Infrastructure cryptographic digest of the exact bytes of a Published Version.

SHA-256 and CID are separate identities.

The SHA-256 value identifies the exact published bytes using the Civic Infrastructure hashing convention.

CID

The CID is the IPFS content identifier assigned to the published object.

A CID identifies specific content.

If the content changes, the resulting publication has a different CID.

A CID is never reassigned to changed content.

Supersedes

Supersedes expresses the relationship between a new Published Version and the earlier Published Version it replaces as the current operative version.

Supersession does not delete, invalidate, or rewrite the earlier publication.

The earlier publication remains historically valid as the version that existed during its applicable period.

Publication Record

A Publication Record is the structured record describing a Published Version.

It records the identities and provenance necessary to identify and verify that publication.

At minimum, a Publication Record should contain:

• artifact identifier;
• version;
• publication status;
• publication date;
• SHA-256;
• CID;
• source Git commit;
• predecessor or superseded version, when applicable.

4. Mutable Discussion and Immutable Publication

Discussion and publication are separate functions.

A human-facing post may be edited, commented upon, discussed, or replaced.

The immutable Published Version identified by its CID is not altered by those activities.

This distinction permits open discussion without sacrificing publication integrity.

A discussion surface may therefore contain:

• the readable current document;
• comments;
• questions;
• proposed changes;
• links to drafts;
• the CID of the authoritative Published Version.

The CID identifies the authoritative immutable publication, not the discussion surrounding it.

5. Publication Lifecycle

The standard lifecycle is:

1. Create or modify a Draft in Gitea.
2. Review and discuss the Draft.
3. Approve the Draft for publication.
4. Freeze the exact publication bytes.
5. Calculate the Civic SHA-256 value.
6. Publish the exact bytes to IPFS.
7. Obtain the CID.
8. Create the Publication Record.
9. Commit the Publication Record to Gitea.
10. Update the relevant human-facing service with the Published Version and CID.
11. Begin the next Draft when a future revision is required.

6. Replacement, Not Mutation

Published artifacts are replaced, not rewritten.

If any content of a Published Version must change:

• the existing publication remains unchanged;
• a new Draft is created;
• the new Draft identifies the earlier Published Version;
• the replacement is separately approved;
• the replacement receives a new SHA-256;
• the replacement receives a new CID;
• the replacement receives a new Publication Record;
• the replacement identifies the earlier version through Supersedes.

The earlier version remains available as part of the publication history.

7. Draft Relationship to the Current Publication

An editable Draft may record the CID of the current Published Version from which it descends.

For example:

Artifact: hubzilla-terms-of-service
Draft-Version: 1.1-draft
Previous-Version: 1.0
Previous-CID: bafy...
Publication-CID: not assigned

The Draft does not reuse the previous CID as its own publication identity.

When the Draft becomes a Published Version, it receives its own CID.

8. Human-Facing Presentation

A Hubzilla post, Portal page, or similar service may display the current Published Version for convenience.

The presentation should clearly identify:

• artifact name;
• current version;
• publication date;
• SHA-256;
• CID;
• relationship to the prior version when applicable.

The presentation should also make clear that the immutable artifact identified by the CID is the authoritative published object.

The human-facing service may remain mutable so that discussion and explanatory material can continue around the publication.

9. Repository Convention

The Civic Infrastructure publication repository should separate source artifacts from publication metadata.

A standard structure may include:

artifacts/
    policies/
    trust/
    specifications/

manifests/

receipts/

Draft and source material belong under artifacts/.

Publication records and manifests belong under manifests/ or another defined metadata location.

Receipts or verification results belong under receipts/.

10. Publication Record Example

A Publication Record may use a simple machine-readable format such as:

artifact: hubzilla-terms-of-service
version: 1.0
status: published
published: 2026-09-30

sha256: <sha256-value>
cid: <ipfs-cid>

source_commit: <git-commit>

supersedes: null

A replacement publication may record:

artifact: hubzilla-terms-of-service
version: 1.1
status: published
published: <date>

sha256: <new-sha256>
cid: <new-cid>

source_commit: <git-commit>

supersedes:
  version: 1.0
  cid: <previous-cid>

11. Infrastructure-Wide Convention

The terms defined in this specification should retain the same meaning across Civic Infrastructure components.

In particular:

• Draft always means editable and unpublished.
• Published Version always means approved immutable publication.
• SHA-256 always identifies the exact published bytes using the Civic convention.
• CID always identifies the IPFS publication object.
• Supersedes always describes replacement without erasure.
• Publication Record always records the publication identities and provenance.

Individual services may present these concepts differently to users, but their meaning should not change.

12. Principle

The Civic Infrastructure separates:

editing from publication, discussion from authority, and replacement from erasure.

This separation preserves both adaptability and historical integrity.