Declare what Festipod needs from ActivityPods, rather than guess it

The Refine seam asks four things of a backend, and the ActivityPods README
answers two: how its providers are configured, and that a declared shape tree
gets its own Data Registration and container on the Pod. It is silent on the
record shape and on whether update replaces or patches — the two the seam
cannot default, and the two that fail silently when wrong.

So the declaration is written before adoption instead of after: the surface is
marked as declared rather than measured, the domain conditions are stated at
full strength, and the two unknowns sit in Needs as requests addressed to the
provider. Reading their source to settle them is the one thing this project
does not do.

This branch had no contract manifest at all, so it gets one. It carries no
consume entry, because neither targeted backend publishes an engagement to
pull; the declaration anchors on the README's commit identity, resolved with
ls-remote, which names a state without fetching any content.
This commit is contained in:
Sylvain Duchesne
2026-10-01 20:14:37 +02:00
parent a5f6e01562
commit d48297fe94
2 changed files with 97 additions and 0 deletions
+24
View File
@@ -0,0 +1,24 @@
# Inter-repo contracts. Festipod is a CONSUMER only: it publishes no interface of its own,
# and what it lists under `publish:` is its own consumer-side DECLARATIONS — the channel a
# provider pulls to learn what this app calls, what it needs, and what blocks it.
#
# Festipod's persistence sits behind interchangeable Refine backends (the backend contract
# itself is in-code: `src/shared/refine/providers/types.ts`). Each candidate backend is a
# separate interface, with its own folder inside `data-layer` — the concept that owns how
# Festipod uses an external data surface.
#
# NO `consume:` SECTION YET, and that is a fact about the providers rather than an omission.
# A `consume:` entry fetches a provider's published engagement; neither targeted backend
# publishes one today. For `@activitypods/refine-providers` the only public specification is
# a README, so the declaration beside it anchors on that repo's commit identity — resolved
# with `git ls-remote`, which names a state without fetching any content. Add the entry the
# moment an engagement exists to pull, or at adoption time through a bounded `reconstruct`.
#
# The iron rule holds regardless: a gap in what a provider publishes is raised in the
# `## Needs` of our declaration, never worked around by reading its source (see
# `data-layer/rule_app-uses-sdk-surface-only` on the sibling branch, and AGENTS.md).
publish:
# Key qualified by interface: a second declaration is coming for the NextGraph+polyfill
# backend, and publish keys must stay unique.
activitypods-providers--festipod: concepts/data-layer/activitypods-providers/usage_festipod.md