@rathnasgala2/schemas 2.12.0 → 2.14.0

package/README.md

@@ -59,36 +59,104 @@ 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 75 MVP operations plus `/internal/health` (76 catalog
-rows; 71 at S0-T07, plus the two SCHEMA-2.8.0 reads and the two SCHEMA-2.10.0
-publication-destination reads/writes). 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 separately generated `fixtures/s4/`
-deployment/certification consumer-fixture family (deployment-intent,
-deployment-observation, deployment-receipt, public-generation-marker, and
-adapter-capability rows for `local-directory`, `github-pages`, and `do-spaces`)
-alongside the existing `fixtures/s2/` family, each with its own manifest.
-LOCAL-21 admits a 21st App route, `/invitations/accept` (`routeId`
-`invitations.accept`), an ordinary `SESSION_REQUIRED` `APP` route (not
-`TRANSACTIONAL_LINK`: it is served by the App origin after sign-in, unlike the
-deferred `/t/**` template family) that 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.
+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, 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
+separately generated `fixtures/s4/` deployment/certification consumer-fixture
+family (deployment-intent, deployment-observation, deployment-receipt,
+public-generation-marker, and adapter-capability rows for `local-directory`,
+`github-pages`, and `do-spaces`) alongside the existing `fixtures/s2/` family,
+each with its own manifest. LOCAL-21 admits a 21st App route,
+`/invitations/accept` (`routeId` `invitations.accept`), an ordinary
+`SESSION_REQUIRED` `APP` route (not `TRANSACTIONAL_LINK`: it is served by the
+App origin after sign-in, unlike the deferred `/t/**` template family) that
+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.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}`
@@ -535,7 +603,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 75 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.12.0",
+  "package": "@rathnasgala2/schemas@2.14.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,12 +1314,15 @@
         "getGithubInstallations",
         "getGithubInstallationsByInstallationIdRepositories",
         "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryBindingsCurrent",
+        "getOrganizationsByOrganizationIdPublicationsByPublicationIdRepositorySetup",
+        "postGithubInstallationsByInstallationIdRepositories",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdConfigurationChangesPlan",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdPublishes",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdPublishesByPublishIdCancel",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryBindings",
         "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesByChangeIdConfirm",
-        "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesPlan"
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositoryChangesPlan",
+        "postOrganizationsByOrganizationIdPublicationsByPublicationIdRepositorySetUp"
       ],
       "componentIds": [
         "AppShell",
@@ -1591,5 +1602,5 @@
       ]
     }
   ],
-  "digest": "sha256:32e5dd41da10ffc018ad79467d80624e614a0276d5bff2c2a5c26a107d0d31b6"
+  "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:548e213c59e1b9bfa105d2cbc9ccde89162293f8337831c97992fd012a8cbe62",
+      "sourceDigest": "sha256:e8c2073c001219a158d458455a8f238c96ce3b7fdb1eb76bcc04388bcf3cc20d",
       "typescriptRootType": null
     }
   ],
-  "digest": "sha256:dc42ec24f4d3e807e75fbd1eed275131434a09c6d7e6940a7f17c1f3b1a3c77d"
+  "digest": "sha256:90e1849ad012f5c649992cde222da04be4e46fcb04fd3de337f4abf866dffed7"
 }

package/openapi/http-catalog.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "2.0.0",
   "sourceDesignRevision": "a53052955ceb6c1aa10c886289dc832eedfe6de0a00004df07d353ac19c4403a",
-  "openApiDigest": "sha256:548e213c59e1b9bfa105d2cbc9ccde89162293f8337831c97992fd012a8cbe62",
+  "openApiDigest": "sha256:e8c2073c001219a158d458455a8f238c96ce3b7fdb1eb76bcc04388bcf3cc20d",
   "operations": [
     {
       "operationId": "getInternalHealth",
@@ -123,6 +123,18 @@
       "actionGrant": "none",
       "sourceFragment": "github"
     },
+    {
+      "operationId": "postGithubInstallationsByInstallationIdRepositories",
+      "method": "POST",
+      "path": "/v2/github/installations/{installationId}/repositories",
+      "purpose": "create a repository on this installation's account",
+      "capabilityKey": null,
+      "conditionalCapabilityKeys": [],
+      "activationGate": "MVP",
+      "assuranceClass": "SESSION",
+      "actionGrant": "none",
+      "sourceFragment": "github"
+    },
     {
       "operationId": "postMembershipInvitationsByTokenAccept",
       "method": "POST",
@@ -464,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",
@@ -476,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",
@@ -574,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",
@@ -612,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",
@@ -624,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",
@@ -636,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",
@@ -929,5 +1049,5 @@
       "sourceFragment": "workloads"
     }
   ],
-  "digest": "sha256:c49369a752150235b9334fa2495e32302daab7afc81d65cc3d58e6b5fb116bdd"
+  "digest": "sha256:abcc06359b67cd9c829bb98687ae3b691fe98b2ba2ea1b23272f5a861c21e41c"
 }