diff --git a/artifacts/specifications/publication-model.md b/artifacts/specifications/publication-model.md new file mode 100644 index 0000000..026fa1b --- /dev/null +++ b/artifacts/specifications/publication-model.md @@ -0,0 +1,291 @@ +# 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: + +```text +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: + +```text +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: + +```yaml +artifact: hubzilla-terms-of-service +version: 1.0 +status: published +published: 2026-09-30 + +sha256: +cid: + +source_commit: + +supersedes: null +``` + +A replacement publication may record: + +```yaml +artifact: hubzilla-terms-of-service +version: 1.1 +status: published +published: + +sha256: +cid: + +source_commit: + +supersedes: + version: 1.0 + 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. \ No newline at end of file