Rhythm 2.0 Specifications

Appearance

CAP-WEB-WEB-012Preserve website edits as attributable revisions

Markdown

CAP-WEB-WEB-012

Preserve website edits as attributable revisions

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-WEB-WEB-04
Exercised by
FAS-WEB-WEB-02-05, FAS-WEB-WEB-04-01, FAS-WEB-WEB-04-02, FAS-WEB-WEB-04-03, FAS-WEB-WEB-04-04, FAS-WEB-WEB-04-05, FAS-WEB-WEB-05-01
Key concepts
CON-WEB-WEB-005, CON-WEB-WEB-004
Actors
ACT-WEB-001, ACT-WEB-007, ACT-WEB-004
Journeys
JNY-WEB-WEB-004
Related
CAP-WEB-WEB-011, CAP-WEB-WEB-013, CAP-WEB-WEB-014, CAP-WEB-WEB-015, CAP-WEB-WEB-016
Proved by
ATS-WEB-WEB-012

Implementation

Executable suites
TST-WEB-WEB-192, TST-WEB-WEB-202, TST-WEB-WEB-205, TST-WEB-WEB-213, TST-WEB-WEB-215, TST-WEB-WEB-234

KindCapabilityProduct areaWebsitesModuleWebsites, content and the portal runtimeRevision1

Read atservices-websites 5fc6823c

Preserve website edits as attributable revisions ​

Purpose ​

Designers need to save work without overwriting another revision or losing the history of the requested change.

How It Works ​

An authorized person opens a change against a site or template. The change records the starting point and its objective. Saves name the revision the designer used and persist work on the change's own branch. Concurrent editing returns a conflict to the losing save. File restrictions keep work within the permitted customer area. Each accepted revision records who or what authored it. The lifecycle determines when another save is possible. History limits refuse further work rather than silently discard earlier entries. A partial repository-to-record failure leaves a conflict for reconciliation rather than forcing the branch backwards.

Relationships ​

Template maintenance opens these changes. Preview and publication consume saved revisions, and pipeline progress explains their later lifecycle.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Preserve website edits as attributable revisions.
Surfaces
consoleapi
Intent sources
services-websites:docs/milestones/rebaseline-2026-10-19.md#1. Approval register (2026-10-15 12:08, 2026-10-18 18:26)services-websites:modules/changes/README.md#Decisions (10, 17)

Controls

52 controls apply, from the corpus control catalogue.

TC-AI-001 TC-AI-003 TC-AI-004 TC-AVL-002 TC-AVL-003 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-005 TC-CHG-006 TC-CHG-007 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-005 TC-DAT-007 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-MON-003 TC-MON-004 TC-PI-001 TC-PI-003 TC-PI-005 TC-SEC-001 TC-SEC-002 TC-SEC-003 TC-SEC-004 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
websites.website-changes.changeapitenant
websites.website-changes.readapitenant
websites.website-changes.sourceservicetenant

Business Rules

15 rules, 14 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
A website change starts Queued for one workspace site or template, with an objective up to 4,000 characters, a full starting commit and a branch named for the change.
proved by ATS-WEB-WEB-012-01, TST-WEB-WEB-202
validationapi, service, databasetest
services-websites:modules/changes/tests/integration/services/persistence/website-changes.integration.spec.js#refuses an objective longer than 4000 characters
02must prove
Proposed
Foreign-workspace sites and changes are indistinguishable from missing records, and rejected creation writes in neither workspace.
proved by ATS-WEB-WEB-012-02, TST-WEB-WEB-202, TST-WEB-WEB-213
invariantservice, databasetest
services-websites:modules/changes/tests/integration/services/persistence/website-changes.integration.spec.js#refuses a site of another tenant as not found, exactly as a site nobody holds
03must prove
Proposed
Revision saving requires the current parent revision, or the starting commit for the first save, and concurrent saves from that parent produce one winner.
proved by ATS-WEB-WEB-012-03, ATS-WEB-WEB-012-13, TST-WEB-WEB-213
invariantservicetest
services-websites:modules/changes/tests/integration/services/revisions/persist-revision.integration.spec.js#lets exactly one of two persists on the same revision through
04must prove
Proposed
Revision saves accept at most 50 regular files of 512 KB within the customer's folder and reject traversal, absolute or backslash paths, duplicate paths, package or source-control folders, symlinks and submodules.
proved by ATS-WEB-WEB-012-04
validationservicetest
services-websites:modules/changes/tests/unit/services/path-policy.spec.ts#refuses another customer's folder
05must prove
Proposed
Saving revisions moves only the website change's branch and leaves the release branch untouched.
proved by ATS-WEB-WEB-012-05, TST-WEB-WEB-213
invariantservicetest
services-websites:modules/changes/tests/integration/services/revisions/persist-revision.integration.spec.js#leaves the release branch at the commit it was at
06must prove
Proposed
A refused revision save records no branch, commit or revision before returning its refusal.
proved by ATS-WEB-WEB-012-04
invariantservicetest
services-websites:modules/changes/tests/integration/services/revisions/persist-revision.integration.spec.js#creates no branch, commit or revision for a refused path, and leaves the change queued
07must prove
Proposed
Saving again during initial preview preparation replaces the current revision, clears the obsolete preview and leaves the change Persisted.
origin: services-websites:modules/changes/README.md#Decisions (17, confirmed by Andrew on 2026-10-18)
proved by ATS-WEB-WEB-012-06, ATS-WEB-WEB-012-12, ATS-WEB-WEB-012-13, ATS-WEB-WEB-012-14, TST-WEB-WEB-205, TST-WEB-WEB-213, TST-WEB-WEB-234
lifecycleservicetest
services-websites:modules/changes/tests/integration/services/persistence/website-changes.integration.spec.js#clears the preview of the earlier revision from the record, the new revision superseding it
08must prove
Proposed
A save is rejected after the lifecycle enters an in-flight pull request, check, build or review stage that no longer accepts revisions.
proved by ATS-WEB-WEB-012-06, TST-WEB-WEB-213, TST-WEB-WEB-234
lifecycleservicetest
services-websites:modules/changes/tests/integration/services/revisions/persist-revision.integration.spec.js#refuses a persist once the change has moved past where a revision is taken
09must prove
Proposed
A change rejects its 101st revision rather than discard earlier revisions.
proved by ATS-WEB-WEB-012-07, TST-WEB-WEB-202
validationdatabase, servicetest
services-websites:modules/changes/tests/integration/services/persistence/website-changes.integration.spec.js#refuses the 101st, naming the limit, rather than dropping one
10must prove
Proposed
State transitions preserve their prior state, actor and context in history and reject the transition that would exceed 1,000 entries.
origin: services-websites:docs/milestones/rebaseline-2026-10-19.md#1. Approval register (2026-10-18 18:26: Refuse at the limit)
proved by ATS-WEB-WEB-012-07, ATS-WEB-WEB-012-11, TST-WEB-WEB-202, TST-WEB-WEB-215
invariantdatabase, servicetest
services-websites:modules/changes/tests/integration/services/persistence/website-changes.integration.spec.js#refuses the transition that would write the 1001st, naming the limit, and keeps the oldest
11must prove
Proposed
Revision authors distinguish people, identified AI runs, staff acting as staff and system-authored template-operation commits.
proved by ATS-WEB-WEB-012-08, ATS-WEB-WEB-012-11, ATS-WEB-WEB-012-15, TST-WEB-WEB-202, TST-WEB-WEB-215
validationserviceobserved
services-websites:modules/changes/db/website-change-revisions.table.ts:REVISION_AUTHOR_KINDS
12must prove
Proposed
Only declared lifecycle transitions are accepted; Rolled Back and Superseded are final, while Failed can restart.
proved by ATS-WEB-WEB-012-09, TST-WEB-WEB-234
lifecycleservicetest
services-websites:modules/changes/tests/unit/services/state-machine.spec.ts#moves queued to persisted on a manual or automated persist
13
Proposed
Change detail includes revisions and the first history page, and diffs compare the current revision with its start, predecessor or a selected revision.
policyapi, servicetest
services-websites:modules/changes/tests/integration/services/revisions/diff-revisions.integration.spec.js
14must prove
Proposed
Opening changes requires change authority, while read authority permits listing and inspection only.
proved by ATS-WEB-WEB-012-10, TST-WEB-WEB-192
permissionapitest
services-websites:modules/changes/tests/e2e/changes-routes.e2e.spec.js#answers 403 to a reader opening a change, which takes websites.website-changes.change
15must prove
Proposed
An unrecorded commit remains on the branch and causes a later parent mismatch refusal; the branch is never forced backwards.
proved by ATS-WEB-WEB-012-16
policyservicedocumented
services-websites:modules/changes/README.md#Decisions (23)

Scenarios

IdGivenWhenThenProvenance
01Two designers edit the same current revision.They submit competing saves.One revision is stored and the other designer must reload after a conflict.test
services-websites:modules/changes/tests/integration/services/revisions/persist-revision.integration.spec.js#refuses the other as a conflict the route answers 409 (StaleObject)

Edge Cases

IdGivenWhenThenProvenance
02The stylesheet-only pilot receives a script-file save.The designer submits that save.The service rejects it before creating a commit.test
services-websites:modules/changes/tests/integration/services/revisions/persist-revision.integration.spec.js#refuses a script, the pilot writing only stylesheets

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software