@rathnasgala2/schemas 2.13.0 → 2.15.0

package/README.md

@@ -59,22 +59,23 @@ removed it as unconsumed -- see "Package layout"). The schema inventory adds the
 separately owned OpenAPI contract as the twenty-first identity and carries
 DEC-091's domain-separated `sourceDesignRevision`. S0-T07 materializes the
 reviewed OpenAPI 3.1 source fragments, deterministic bundle, and digest-bound
-HTTP catalog for exactly 76 MVP operations plus `/internal/health` (77 catalog
+HTTP catalog for exactly 85 MVP operations plus `/internal/health` (86 catalog
 rows; 71 at S0-T07, plus the two SCHEMA-2.8.0 reads, the two SCHEMA-2.10.0
-publication-destination reads/writes, and the SCHEMA-2.13.0 repository create).
-The bundle includes the accepted DEC-097 receipt-exchange and deployment-receipt
-amendments and serializes the fixed OpenAPI Generator 7.25.0 option sets. Every
-operation also declares its tenant scope, lifecycle and activation guards, maps
-every reachable problem, and carries schema-validated nominal and problem
-examples. S0-T08 projects the exact 19 admitted transition families into 77
-independently identified event actions (SCHEMA-2.11.0 adds the
-`github_installation` family so the worker-only compare-and-set writer can
-retire into the sole aggregate gateway). Each action binds its aggregate and
-organization or publication scope, exact predecessor/target states, the closed
-DEC-101 payload, the transactional outbox producer, and a non-empty registered
-consumer set. S5-T00 materializes document 07's closed 15-component App semantic
-catalog and document 14's 20-entry MVP App route registry (S5 brief section 4)
-as `docs/catalogs/app-components.json` and `docs/catalogs/app-routes.json`, with
+publication-destination reads/writes, the SCHEMA-2.13.0 repository create, and
+the nine SCHEMA-2.14.0 write/preview/publish operations). The bundle includes
+the accepted DEC-097 receipt-exchange and deployment-receipt amendments and
+serializes the fixed OpenAPI Generator 7.25.0 option sets. Every operation also
+declares its tenant scope, lifecycle and activation guards, maps every reachable
+problem, and carries schema-validated nominal and problem examples. S0-T08
+projects the exact 19 admitted transition families into 77 independently
+identified event actions (SCHEMA-2.11.0 adds the `github_installation` family so
+the worker-only compare-and-set writer can retire into the sole aggregate
+gateway). Each action binds its aggregate and organization or publication scope,
+exact predecessor/target states, the closed DEC-101 payload, the transactional
+outbox producer, and a non-empty registered consumer set. S5-T00 materializes
+document 07's closed 15-component App semantic catalog and document 14's
+20-entry MVP App route registry (S5 brief section 4) as
+`docs/catalogs/app-components.json` and `docs/catalogs/app-routes.json`, with
 every `apiOperationIds` entry validated against `openapi/openapi.yaml`, every
 `componentIds`/`contentKeyIds` entry validated against the component catalog,
 and `capabilityKeys` projected from `openapi/http-catalog.json`. S4-T01 adds the
@@ -90,6 +91,97 @@ calls `postMembershipInvitationsByTokenAccept`; its non-enumerating failure
 states collapse onto that operation's single declared `INVALID_SOURCE_STATE`
 problem, which covers an expired, already-used or unknown token alike.
 
+SCHEMA-2.15.0 closes a Content-list gap SCHEMA-2.14.0 left: with `kind` the only
+fact the inventory carried about a flat file, a row could not show title, kind,
+status or last-changed, and a client could not check web-address uniqueness,
+without one round trip per row. `ContentInventoryItem` gains two optional
+members, exactly one of which the server returns on every item from this version
+on: `summary` (`ContentInventoryItemSummary` --
+`contentId`/`title`/`slug`/`status`/`language`/`createdAt` required,
+`updatedAt`/`publishedAt` optional; `status` is the new closed
+`ContentItemStatus`, `DRAFT`/`PUBLISHED`/`UNLISTED`/`ARCHIVED`) when the header
+block the server now reads for every listed path parses, or `unreadable`
+(`ContentInventoryItemUnreadable`, `{reason}`, the new closed
+`ContentItemUnreadableReason`: `HEADER_MISSING`/`HEADER_UNPARSABLE`/
+`HEADER_INVALID`/`TOO_LARGE`) when it does not. `kind` itself now comes from the
+header when `summary` is present, from the content root as before when it is
+not. This is stated in the operation description rather than schema- enforced,
+because a `oneOf` requiring one of the two would make a pre-2.15.0 item -- one
+with neither field, valid until now -- invalid; member types reuse
+`content-frontmatter.schema.json`'s `$defs`, matching how
+`ContentFrontmatter`/`ContentPublicationSummary` already do. `GET .../content`
+also gains its own `limit` bound (`ContentLimit`): default 50 in place of the
+shared default of 25, the existing 100 maximum kept unchanged since lowering a
+maximum is never additive; the server may return fewer items than `limit` even
+when more are available.
+
+SCHEMA-2.14.0 (design `scrap/20260928_write-preview-publish.md` section 3) is
+additive, closing the write/preview/publish content journey. Nine operations
+join the contract under
+`/v2/organizations/{organizationId}/publications/{publicationId}`:
+`GET .../content` (bounded git-trees inventory at the main branch head,
+`items[].kind` ARTICLE/PAGE derived from the content root, never from parsing
+the file; the required `publication` object -- `defaultLanguage`, `theme`, and
+up to 200 `authors` -- is read from `gala/repository.json`,
+`gala/appearance.json` and `gala/authors/` at the same main head and returned on
+every page, not only the first, carrying no personal data beyond what each
+author file itself publishes), `GET .../content/documents` and
+`GET .../content/assets` (one document or one binary image, `revision` omitted
+meaning the main head and otherwise enforced against the database -- the main
+head, this publication's own `RepositoryChange`'s `proposedRevision` or
+`baseRevision`, or its own published revision -- never accepted on the caller's
+assertion), `GET`/single-read `.../repository-changes` (list and read proposed
+changes across every plan kind, modelled on the reviews list and read),
+`POST .../repository-changes/{changeId}:bring-up-to-date` (a file-level
+three-way merge from blob ids only, never a text merge: every path merging
+cleanly plans a new change and returns `201`; any path conflicting writes
+nothing and returns `409 INVALID_SOURCE_STATE` naming each conflicting path, so
+the App merges the text itself in the browser from the document read and submits
+a new `content-changes:plan`), `POST .../repository:set-up` and
+`GET .../repository/setup` (add the user template repository's missing files to
+an already-linked repository, never overwriting a path that exists with
+different content), and `POST .../publishes/{publishId}:update-default-branch`
+(retry moving the linked repository's default branch forward after GitHub
+refused it). `content-changes:plan` is extended, additively: the 2.13.0
+single-document shape (`path`, `contentDigest`, `expectedHead`) stays accepted,
+and a new batch shape (`baseRevision` plus `documents[]`/`assets[]`, each entry
+`PUT` or `DELETE`, up to 20 of each, a document capped at 1 MiB and an asset at
+5 MiB) plans up to 20 MiB in one change; every path is checked against a closed
+safety pattern that makes `gala/`, `gala.lock.json`, `.github/`,
+dot-directories, absolute paths, `..` segments, backslashes and control
+characters unrepresentable, and every asset write names its `contentType` from
+the same five-member closed list the asset read serves (`image/svg+xml` is
+deliberately not among them). A stale `expectedHead`/`baseRevision` is
+`409 INVALID_SOURCE_STATE` carrying the live main head on the new
+`X-Gala-Current-Head` response header, so the App can merge without ever holding
+a commit id itself; `bring-up-to-date`'s file-level conflict reuses the same
+header, with one `errors[]` entry per conflicting path
+(`code: CONTENT_CONFLICT`, `pointer` a JSON Pointer under `/documents/` or
+`/assets/`). `RepositoryChangeSummary` gains `baseRevision` (required for a
+`CONTENT`-kind change), `proposedRevision` (absent until the commit exists), and
+`broughtUpToDateFromChangeId`. `POST .../publishes` gains the declared refusal
+`SOURCE_OUT_OF_DATE` (an `errors[].code` on the same `409 INVALID_SOURCE_STATE`,
+pointed at `/sourceRevision`, described in prose alongside the existing
+`/scheduledFor` cause since the generator admits one example per problem code
+per operation): a publish is refused unless the current default-branch head is
+an ancestor of the revision being published, which is what a verified publish's
+own worker then fast-forwards the default branch to, non-forced, retryable
+through `update-default-branch` when GitHub reports the branch protected
+(`BLOCKED_BY_PROTECTION`) or moved since (`DIVERGED`) -- the site stays live
+either way. `DeploymentSummary` gains the optional `defaultBranchUpdate` block
+(`state` PENDING/UPDATED/BLOCKED_BY_PROTECTION/DIVERGED/FAILED, optional
+`updatedAt`), and repository creation's `startFrom` (`USER_TEMPLATE`, the
+default, or `EMPTY`) chooses whether the created repository generates from the
+`rathnasgala2/user-template` GitHub template. `docs/catalogs/app-routes.json`'s
+Content route gains the new operation ids and its `screenJob` no longer says the
+screen is unavailable; the Source route gains the two set-up operations and
+Releases gains the default-branch retry. The 15-component App semantic catalog
+and its shared closed state vocabulary already cover every state this journey
+needs, so `catalog-sources/app-components.json` is unchanged. The 80-domain
+digest inventory, every existing operation id, schema, enum member and required
+field are unchanged; a consumer pinned to 2.13.0 changes nothing but the package
+version to move to 2.14.0.
+
 SCHEMA-2.7.1 (LOCAL-50) adds the optional operation-level vendor extension
 `x-gala-conditional-capability-keys`: an array of `{capabilityKey, condition}`
 pairs naming an alternate capability key that also admits the operation, next to
@@ -535,7 +627,7 @@ remediation, and documentation URL fields without including authored values.
   fragments grouped by the first literal resource token. A build input, not part
   of the npm payload (SCH-H7: `!openapi/source/` in `package.json`'s `files`) --
   a consumer reads the materialized `openapi/openapi.yaml` instead.
-- `openapi/openapi.yaml` — deterministic OpenAPI 3.1 bundle for the exact 76 MVP
+- `openapi/openapi.yaml` — deterministic OpenAPI 3.1 bundle for the exact 85 MVP
   operations plus health.
 - `openapi/http-catalog.json` — generated digest-bound method/path/purpose and
   capability inventory, including `conditionalCapabilityKeys` (SCHEMA-2.7.1) and

package/THIRD_PARTY_LICENSES.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "package": "@rathnasgala2/schemas@2.13.0",
+  "package": "@rathnasgala2/schemas@2.15.0",
   "source": "package-lock.json",
   "dependencies": [
     {

package/docs/catalogs/app-components.json

@@ -2286,7 +2286,7 @@
     },
     {
       "contentKey": "organizations.by-organization-id.publications.by-publication-id.content.screen.ready.summary",
-      "defaultMessage": "Browsing and editing this publication's content is not available yet.",
+      "defaultMessage": "Write, preview, propose, review and publish this publication's content, with drafts kept in the browser until proposed.",
       "description": "Summary for the organizations.by-organization-id.publications.by-publication-id.content screen, copied verbatim from document 14's Screen/job cell.",
       "placeholders": {},
       "sensitivity": "AUTHENTICATED"
@@ -4707,5 +4707,5 @@
       "sensitivity": "PUBLIC"
     }
   ],
-  "digest": "sha256:d5610f4528de71e2293bc30198e1e47247cd4b910da549fa1721ddd72faa499d"
+  "digest": "sha256:3c8f46cb53c89980a26d8d4134d0f8bdd72d80cd96576a24baec31edf335ce2a"
 }

package/docs/catalogs/app-routes.json

@@ -972,7 +972,13 @@
       "capabilityKeys": ["publication.source.write", "publication.view"],
       "apiOperationIds": [
         "getOrganizationsByOrganizationIdPublicationsByPublicationId",
-        "postOrganizationsByOrganizationIdPublicationsByPublicationIdContentChangesPlan"
+        "getOrganizationsByOrganizationIdPublicationsByPublicationIdContent",
+        "getOrganizationsByOrganizationIdPublicationsByPublicationIdContentAssets",
+        "getOrganizationsByOrganizationIdPublicationsByPublicationIdContentDocuments",
+        "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChanges",
+        "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesByChangeId",
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdContentChangesPlan",
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesByChangeIdBringUpToDate"
       ],
       "componentIds": [
         "AppShell",
@@ -1060,7 +1066,8 @@
         "getOrganizationsByOrganizationIdPublicationsByPublicationIdDeploymentsByGenerationId",
         "postOrganizationsByOrganizationIdOperationsByOperationIdCancel",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdDeploymentsByGenerationIdReconcile",
-        "postOrganizationsByOrganizationIdPublicationsByPublicationIdDeploymentsRollback"
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdDeploymentsRollback",
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdPublishesByPublishIdUpdateDefaultBranch"
       ],
       "componentIds": [
         "AppShell",
@@ -1298,7 +1305,8 @@
         "publication.publish",
         "publication.schedule",
         "publication.settings.manage",
-        "publication.source.write"
+        "publication.source.write",
+        "publication.view"
       ],
       "apiOperationIds": [
         "deleteOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryBindingsCurrent",
@@ -1306,13 +1314,15 @@
         "getGithubInstallations",
         "getGithubInstallationsByInstallationIdRepositories",
         "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryBindingsCurrent",
+        "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositorySetup",
         "postGithubInstallationsByInstallationIdRepositories",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlan",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdPublishes",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdPublishesByPublishIdCancel",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryBindings",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesByChangeIdConfirm",
-        "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesPlan"
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesPlan",
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositorySetUp"
       ],
       "componentIds": [
         "AppShell",
@@ -1592,5 +1602,5 @@
       ]
     }
   ],
-  "digest": "sha256:d2eccb738dcd301d9e83a6ce0ef7dd8ed4e71f6f6f4fa7e67126c2ef0a99e84b"
+  "digest": "sha256:80401d17e9366bb0c496db9c2fe7520a7f106b1fef24d3c1be11b4cace48581d"
 }

package/docs/catalogs/schema-inventory.json

@@ -209,9 +209,9 @@
       "version": "2.0.0",
       "path": "openapi/openapi.yaml",
       "materialized": true,
-      "sourceDigest": "sha256:5d997a363085652fa2d78b6ffd7f3e307edabecbcb18cc56ed785353bcf33896",
+      "sourceDigest": "sha256:ca5cf80a6fc7b91e4a029d9962efc0da84b31a267b0e1a7bbaaba731d426dffc",
       "typescriptRootType": null
     }
   ],
-  "digest": "sha256:c98e1d350d67018d609def3606d02049bb6acc5b5bb165912606d5215fdd3623"
+  "digest": "sha256:fe8e29466fbeaafd38b28e6d09f94a4f9e05045aaa4af954431d5b493a13ba14"
 }

package/openapi/http-catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "2.0.0",
   "sourceDesignRevision": "a53052955ceb6c1aa10c886289dc832eedfe6de0a00004df07d353ac19c4403a",
-  "openApiDigest": "sha256:5d997a363085652fa2d78b6ffd7f3e307edabecbcb18cc56ed785353bcf33896",
+  "openApiDigest": "sha256:ca5cf80a6fc7b91e4a029d9962efc0da84b31a267b0e1a7bbaaba731d426dffc",
   "operations": [
     {
       "operationId": "getInternalHealth",
@@ -476,6 +476,18 @@
       "actionGrant": "none",
       "sourceFragment": "organizations"
     },
+    {
+      "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdContent",
+      "method": "GET",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/content",
+      "purpose": "inventory this publication's content at the main branch head",
+      "capabilityKey": "publication.view",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
     {
       "operationId": "postOrganizationsByOrganizationIdPublicationsByPublicationIdContentChangesPlan",
       "method": "POST",
@@ -488,6 +500,30 @@
       "actionGrant": "none",
       "sourceFragment": "organizations"
     },
+    {
+      "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdContentAssets",
+      "method": "GET",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/content/assets",
+      "purpose": "read one content asset",
+      "capabilityKey": "publication.view",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
+    {
+      "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdContentDocuments",
+      "method": "GET",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/content/documents",
+      "purpose": "read one content document",
+      "capabilityKey": "publication.view",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
     {
       "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdDeployments",
       "method": "GET",
@@ -586,6 +622,18 @@
       "actionGrant": "none",
       "sourceFragment": "organizations"
     },
+    {
+      "operationId": "postOrganizationsByOrganizationIdPublicationsByPublicationIdPublishesByPublishIdUpdateDefaultBranch",
+      "method": "POST",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/publishes/{publishId}:update-default-branch",
+      "purpose": "retry moving the default branch forward to a published revision",
+      "capabilityKey": "publication.publish",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
     {
       "operationId": "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryBindings",
       "method": "POST",
@@ -624,6 +672,18 @@
       "actionGrant": "none",
       "sourceFragment": "organizations"
     },
+    {
+      "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChanges",
+      "method": "GET",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/repository-changes",
+      "purpose": "list proposed repository changes of this publication",
+      "capabilityKey": "publication.view",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
     {
       "operationId": "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesPlan",
       "method": "POST",
@@ -636,6 +696,30 @@
       "actionGrant": "none",
       "sourceFragment": "organizations"
     },
+    {
+      "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesByChangeId",
+      "method": "GET",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/repository-changes/{changeId}",
+      "purpose": "read one proposed repository change",
+      "capabilityKey": "publication.view",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
+    {
+      "operationId": "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesByChangeIdBringUpToDate",
+      "method": "POST",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/repository-changes/{changeId}:bring-up-to-date",
+      "purpose": "plan a new change merging a proposed change onto the current main head",
+      "capabilityKey": "publication.source.write",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
     {
       "operationId": "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesByChangeIdConfirm",
       "method": "POST",
@@ -648,6 +732,30 @@
       "actionGrant": "none",
       "sourceFragment": "organizations"
     },
+    {
+      "operationId": "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositorySetUp",
+      "method": "POST",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/repository:set-up",
+      "purpose": "add the user template files to a linked repository that lacks them",
+      "capabilityKey": "publication.integrations.manage",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
+    {
+      "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositorySetup",
+      "method": "GET",
+      "path": "/v2/organizations/{organizationId}/publications/{publicationId}/repository/setup",
+      "purpose": "read this publication's repository set-up state",
+      "capabilityKey": "publication.view",
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "organizations"
+    },
     {
       "operationId": "getOrganizationsByOrganizationIdPublicationsByPublicationIdReviews",
       "method": "GET",
@@ -941,5 +1049,5 @@
       "sourceFragment": "workloads"
     }
   ],
-  "digest": "sha256:002edc7aa9c72f1b459d3d534af24c1f00fb4a6fd1d94bbcec5f611eb58eca77"
+  "digest": "sha256:f4c2d4b69632958faefc39a1a229877a70a60b86a22b9e891bbecb1924878c68"
 }