From 6539275c55fceafe4eec1c14d93cd1a5868116c1 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Thu, 9 Jul 2026 12:31:55 +0200 Subject: [PATCH] Sync wiki from project files --- Repo-docs-MODULE-ARCHITECTURE.md | 41 ++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/Repo-docs-MODULE-ARCHITECTURE.md b/Repo-docs-MODULE-ARCHITECTURE.md index 3930cea..9c1d5f0 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.md +++ b/Repo-docs-MODULE-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. > Origin: `repository`. @@ -69,6 +69,18 @@ New code should avoid deepening these compatibility dependencies. Prefer explici Core must not import module feature pages or module business logic directly. It should interact with modules through manifests, entry points, metadata, capabilities, events, and route contributions. +The compatibility/deprecation plan for the current split line is: + +- keep documented public compatibility imports until the owning module exposes a + stable replacement and all in-tree callers have migrated +- remove deep implementation re-export modules once callers can use module-owned + public APIs or kernel capabilities +- preserve migration/table compatibility for already-created development and + release databases +- document remaining compatibility surfaces here and in the owning module README +- reject new cross-module imports that bypass manifests, capabilities, events, + or public module APIs + ## Stable Kernel Contracts The following contracts are the baseline API that modules can rely on: @@ -90,6 +102,11 @@ The following contracts are the baseline API that modules can rely on: Changes to these contracts must be versioned or accompanied by compatibility shims. +This list is the Milestone A kernel-contract freeze baseline. New module work +may extend the kernel by adding explicit contracts, but existing contracts must +remain source-compatible through the 0.1.x split line unless a migration shim +and deprecation note are provided. + Known access-related capability names are defined in `govoplan_core.core.access`, including: @@ -237,10 +254,24 @@ Modules should record changes with: - `payload`: small, non-secret routing metadata that helps determine whether a tombstone belongs to the requested view. -The first concrete consumer is `GET /api/v1/files/delta`. Without `since`, it -returns the current files/folders snapshot for the requested owner/campaign -scope. With `since=seq:`, it returns changed files, changed folders, -and tombstones for resources that left the current view. +If a retained sequence window is introduced, endpoints must compare the +incoming watermark with the oldest retained sequence entry for their module and +collections. A watermark older than that window is not safe for incremental +replay, so the endpoint must return a full snapshot with `full: true`. + +Concrete consumers: + +- `GET /api/v1/files/delta`: without `since`, returns the current files/folders + snapshot for the requested owner/campaign scope. With `since=seq:`, + returns changed files, changed folders, and tombstones for resources that + left the current view. +- `GET /api/v1/campaigns/delta`: returns accessible campaign rows and campaign + tombstones when ownership, sharing, or soft deletion removes a campaign from + the current list. +- `GET /api/v1/campaigns/{campaign_id}/workspace/delta`: returns a workspace + snapshot first, then changed campaign/version metadata and optional summary + refreshes when version, job, issue, or delivery-attempt changes invalidate the + workspace view. ## Module Responsibilities