Keep sign-ups unlinkable on ActivityPods, and land the pending coherence-pass work
Participation privacy (decision_2026-10-29_participation-privacy-mechanism): a sign-up is a private Join naming the meeting point, addressed to nobody, handled by the backend on emission. Attendee lists hold member URNs hashed from (WebID, event, a secret kept in the participant's profile), so counts stay public and only contacts recognise anyone; the creator has no read right and is notified anonymously. Each person's participations collection, created by the backend at the first sign-up, is readable by their /contacts WAC group only, never world-readable. The member URN is sticky per (meeting point, participant) and every collection write is verified by reading back, so a refused write leaves the act unrecorded and retryable. The EventRef mechanism and its browser-side provisioning are gone. The backend now runs with WebACL on, as the reference apps do, on its own secure datasets festipod / settings-festipod instead of the pod provider's settings dataset; pod-notifications needs it. The compose header and the deployment leaf say how to reset a stack whose datasets predate this. The rights matrix covers the new mechanism live (148 hard lines), including a forged contact Accept between throwaway accounts: the stranger enters the contacts list (platform defect, reported upstream) but is refused the profile and the participations. Tests may attack as long as they never break the dev environment (rule_tests-never-break-the-dev-environment). Also lands the coherence-pass work that was still uncommitted: contacts as the Pod's social graph and invite links, image upload to the Pod, the meeting-point form, profile completion gate, and the doctrine for them. Superseded briefs and decisions are deleted rather than annotated.
This commit is contained in:
Sylvain Duchesne
@@ -8,7 +8,7 @@ against: 66616484b96fb2227cd8cdf02321aacfb4811365
|
||||
|
||||
Festipod is a mobile-first web application: users create **meeting points** grafted onto public events, and sign up to them. Its entire persistence goes through Refine, behind a **backend seam** that exists so the app can support several Refine backends and let the user switch between them at runtime. This package is one of the two backends targeted; the other is a Refine provider over NextGraph plus its polyfill. The seam's own contract — what a backend must answer before it can be added — lives in code, in `src/shared/refine/providers/types.ts`.
|
||||
|
||||
The seam is wired since 2026-10-09 (T04.e): this backend is the registered default, and Festipod reads and writes through it — `useList` over the shared `as:Event` container (split into events and meeting points by the bindings' `isInstance`), creates and updates through the data provider, and the embedded `apods:attendees` collection through the participation binding's `membersOf`. Joins/leaves are the one write beside Refine (the package implements no `custom`): an `as:Join`/`as:Leave` posted to the user's own outbox by `src/shared/data/outbox.ts`, per the platform flow recorded in the 2026-10-09 brief. What the list below declares is therefore measured where a runtime check exists and declared elsewhere; `against:` names the observation's commit, and the package publishes no engagement, so there is nothing to pull and nothing that can drift — what is recorded here is read against our own reconstruction, and re-read when it is re-stamped.
|
||||
The seam is wired since 2026-10-09 (T04.e): this backend is the registered default, and Festipod reads and writes through it — `useList` over the shared `as:Event` container (split into events and meeting points by the bindings' `isInstance`), creates and updates through the data provider, and the embedded `apods:attendees` collection through the participation binding's `membersOf`. Joins/leaves are the one write beside Refine (the package implements no `custom`): an `as:Join`/`as:Leave` posted to the user's own outbox by `src/shared/data/outbox.ts`, naming the meeting point with no addressee, so that only its author and the app can read it. What the list below declares is therefore measured where a runtime check exists and declared elsewhere; `against:` names the observation's commit, and the package publishes no engagement, so there is nothing to pull and nothing that can drift — what is recorded here is read against our own reconstruction, and re-read when it is re-stamped.
|
||||
|
||||
## Consumed surface
|
||||
|
||||
@@ -32,6 +32,8 @@ Four resources, one per persisted entity: **events**, **meeting points**, **part
|
||||
|
||||
Through Refine's hooks only, never the provider directly: `useList` → `getList`, `useCreate` → `create`, `useUpdate` → `update`, `useDelete` → `deleteOne`. `getOne` is reached by Refine's cache plumbing rather than an explicit call. The app mounts Refine with `liveMode: 'auto'` and `mutationMode: 'optimistic'`.
|
||||
|
||||
`update` of the own profile is also how the participation secret is stored: before the first Join the app re-reads its profile explicitly (`getOne`, refetched, never trusting a cached copy), and when no secret is there writes `http://festipod.org/participationSecret` through `update` with the **full IRI** as the key, then reads the stored value back from the answer. The pod stores and returns such a predicate under the full IRI (verified live 2026-10-29 with the app's token), whatever the `fp` prefix registration.
|
||||
|
||||
`create` of an event or a meeting point carries `to: as:Public` among its variables: Festipod's declaration that the record is public, on which the Festipod backend's public read and discovery listing depend. See constraint 10.
|
||||
|
||||
### Record handling
|
||||
@@ -51,7 +53,7 @@ What must keep holding for this backend to serve the app.
|
||||
1. **Festipod's own vocabulary, not ActivityStreams.** The four entities are Festipod domain types defined by SHEX shapes this repo holds; none is an ActivityStreams type. A caller-supplied `jsonContext` and caller-supplied `types` are what make that possible, and both must stay caller-supplied.
|
||||
2. **The identifier a record is addressed by must stay the identifier other records reference.** The seam carries the two separately because they differ on the other targeted backend; here they coincide, and the app relies on that. Splitting them later would break every cross-entity reference silently.
|
||||
3. **A partial update must stay partial.** The app sends only changed fields. A move to replacing the resource would drop every field omitted, with no error.
|
||||
4. **Every participation must be readable by every user.** The participant count is the number of participations of an event, counted with no filtering. What is confidential is the **link between a participation and a person** — only a connection can read the profile a participation points at and recognise who it is — never the participation record itself. The provider alone cannot satisfy it (need 1).
|
||||
4. **Every participation must be readable by every user.** The participant count is the number of participations of an event, counted with no filtering. What is confidential is the **link between a participation and a person**: an attendee list holds opaque member URNs, and only a connection, who reads the secret on the person's profile, can recognise who a URN is — never the list itself. The provider alone cannot satisfy it (need 1).
|
||||
5. **The count is never a stored, incremented field.** Reading a counter, adding one and writing it back derives each write from a read of the previous one and races itself through any data provider. This is measured, not theoretical, and it is why the app derives the count from the participation list at read time.
|
||||
6. **Changes must be pushed, not polled.** Neither the app nor its BDD suites has a polling loop, and adding one is ruled out by project doctrine. `liveMode: 'auto'` is mounted on that basis.
|
||||
7. **No process-global state that outlives a remount.** Two backends coexist in one page and the user switches between them at runtime; switching remounts Refine to discard the cache of the backend being left. Building this backend's providers must have no side effect that accumulates across switches — see friction 1, which is where this currently bites.
|
||||
@@ -65,7 +67,7 @@ What must keep holding for this backend to serve the app.
|
||||
2. **`getList` fetches the whole container on every call.** Filtering, sorting and pagination run in memory afterwards, so the cost of listing an event's participations grows with the user's total number of participations rather than with the event. No workaround; it is why a filter on a `getList` buys nothing beyond convenience.
|
||||
3. **A list subscription reports membership only.** A container channel delivers `Add`/`Remove`, not a member's own fields changing, so a list of events does not refresh when an event's title, place or time is edited. Watching each record instead would open one channel per row. The event list is exactly the screen where this is visible.
|
||||
4. **`types` takes precedence over `shapeTreeUri`, the opposite of what the configuration type documents.** The declared behaviour is that `types` is "only used as a fallback when `shapeTreeUri` is not set"; a resource setting both is in fact resolved from `types`. Establishing which one actually wins cost a read of the resolution path. Configuring exactly one avoids it, but the documentation should say which wins.
|
||||
5. **The member shape of an `apods:attendees` collection is not pinned anywhere Festipod may read at work time.** The reconstruction documents the container discovery, not what a membership record is: a bare actor URI, or an object carrying event/participant/status. The project reconnaissance records only that a join "adds the actor to the collection" and that members come back "as full objects for a reader who is allowed, and as URIs otherwise". The ActivityPods backend's participation binding is designed against that: a member maps to `{ id, userId, isConfirmed: true }` (membership IS the attendance), with `eventId` supplied by the reader — the event the collection was read from — because a member carries no event link. The first runtime read against the local platform (T04.g) must confirm or correct this mapping.
|
||||
5. **The member shape of an `apods:attendees` collection is not pinned anywhere Festipod may read at work time.** The reconstruction documents the container discovery, not what a membership record is. Read against a local platform (verified 2026-10-12), the collection is its own resource, linked from the meeting point by URI and never embedded; its items are, in Festipod, opaque member URNs recorded by the Festipod backend, and the participation binding maps each to `{ id, userId, isConfirmed: true }` (membership IS the attendance), `eventId` being supplied by the reader — the meeting point the collection was read from. The `userId` of such a record is a member URN, not a person: a person is recognised only by hashing (see constraint 4).
|
||||
|
||||
6. **The live provider's `subscribe` rejects with an uncaught `Forbidden` when the Pod refuses its push channel.** On this platform the channel creation (`POST /.notifications/WebSocketChannel2023`) answers 403 for the app's session, and each refusal surfaces as one unhandled rejection in the page — raised inside the provider, where the app cannot catch it; Festipod's end-to-end checks recognise it by its throw site. Reporting the refusal through the subscription's error path would let the app handle it.
|
||||
|
||||
|
||||
@@ -1,97 +0,0 @@
|
||||
---
|
||||
type: brief
|
||||
summary: Target model for sign-ups — a Participation READABLE by everyone (event ref + `active` boolean + a key-less reference to the participant's profile), deposited into the event's inbox; the creator processes the inbox, dedups WITHOUT knowing who, files the reference into a Set on the event and PURGES the cancelled ones; count = Set.size with no filtering (accepted upper bound); only connections can read the profile and recognize the person. Supersedes the mutated counter + plaintext userId.
|
||||
---
|
||||
|
||||
# Brief (2026-07-20, revised 2026-07-27) — Set-based sign-ups
|
||||
|
||||
## The model
|
||||
|
||||
Laid down and refined by the PO on 2026-07-27. Everything is **keys and URLs** — no roles, no membership, no allow-list.
|
||||
|
||||
1. The participant creates a **Participation** object, **readable by everyone**, holding: the **reference to the event**, an **`active` boolean**, and a **reference to their *protected* profile that carries no key**. **Nothing else** — no description for now.
|
||||
2. They deposit the **Participation's reference** into the **event's inbox**.
|
||||
3. The **creator** processes their inbox **automatically**, as soon as they are online.
|
||||
4. They **dedup** (see below) — **without knowing who the participant is**: they hold a name for the profile, not the key to read it.
|
||||
5. They file a **reference** to the Participation into a **Set** carried by the event's document.
|
||||
6. Anyone reads **`Set.size`** → the number of participants.
|
||||
7. Someone **connected** to the participant holds their profile's cap, reads it, and **recognizes** the person.
|
||||
|
||||
**Withdrawal**: the participant sets `active` to false **on their own object**. The creator sees it when reading, and **purges** — removing the reference from the Set.
|
||||
|
||||
Three properties follow: **anonymous attendance by default** (even the creator cannot see who); **nobody modifies anyone else's sign-up** (only the participant holds the write key to their own object); **no plaintext `userId`** ever travels.
|
||||
|
||||
### The principle that holds it all together: the truth is in the object, messages are only hints
|
||||
|
||||
The object **controlled by the participant** is what counts. Any message — an inbox deposit, a purge notification — is only a **hint** that triggers a check, never an authority.
|
||||
|
||||
Consequence: **forgery becomes structurally harmless**. A fake « purge X » leads the creator to read X, find it still active, and do nothing. That is why inbox deposits **need not be signed** — which is just as well, since the contract promises no authenticated sender.
|
||||
|
||||
### Why a flag rather than a deletion
|
||||
|
||||
Without the read key, a **deletion** cannot be told apart from "nothing was ever there". A **readable** object carrying a **flag** transforms the problem: the cancellation no longer has to be *detected*, it is simply *read*. The blocker disappears instead of being worked around with a forgeable message.
|
||||
|
||||
### Why the identity pointer targets the existing profile
|
||||
|
||||
No need for a second document per participation: the participant's **protected profile** already plays that role, and their connections **already** hold the key to read it — that is the very definition of being connected. A third party sees an opaque reference.
|
||||
|
||||
The advantage over an encrypted field inside the Participation: **adding a connection rewrites nothing**. The profile is shared with a new connection once, durably (and irreversibly — the contract publishes no revocation). An encrypted field would require re-encrypting to N recipients and rewriting the Participation on every new connection.
|
||||
|
||||
## What this rests on
|
||||
|
||||
Two guarantees the contract publishes, and one thing it does not.
|
||||
|
||||
| What the model needs | Where it stands |
|
||||
|---|---|
|
||||
| A reference can **name without granting read access** | Published: *"A returned reference carries no key… A reference found inside a document yields a name, not a key."* |
|
||||
| Sharing is **per document, durable and one-way** | Published: `inbox.share(doc, toUser)` — one act, no revocation, nothing per reader on a public document |
|
||||
| **Anyone may deposit, only the owner reads** the inbox | Published: `inbox.postToDocument` / `inbox.read` |
|
||||
| A **dedup key** letting the creator count distinct people without reading them | **NOT published.** See below — this is the open dependency. |
|
||||
|
||||
## The dedup: the requirement, and the gap
|
||||
|
||||
**The requirement, validated by the PO (2026-07-27)**: the creator must be able to tell two references from the *same* person apart from two references from *different* people, **without ever knowing who** — otherwise the count is not a count of people, and a participant could inflate it by creating several Participations.
|
||||
|
||||
**The contract publishes nothing that does this.** A reference "yields a name, not a key", and no call answers "do these two references belong to one person?". So the mechanism is **not Festipod's to specify**: it is a **gap to raise with the provider**, stated as a need — *a stable, per-person discriminator that can be compared without reading the referenced document*.
|
||||
|
||||
Design consequence, whatever the mechanism turns out to be: the Set is **keyed by that discriminator** — at most one reference per person. `Set.size` = the number of distinct people.
|
||||
|
||||
### The reservation that must outlive this brief
|
||||
|
||||
Any such discriminator is by construction a **pseudonym**: it does not say *who*, but it is comparable across contexts, so whoever collects references can link them. **Never present a Festipod action as "anonymous"** when it circulates one — the contract guarantees no anonymity, and making the Participation public widens the surface on which it is collected. Whether the pseudonym can be rotated, or scoped, is part of the gap above.
|
||||
|
||||
## Trade-offs deliberately accepted (PO, 2026-07-27)
|
||||
|
||||
- **No filtering on read.** The count is `Set.size`, **without** checking the `active` flags. We accept the **staleness risk**: a cancelled participation still counts until the creator has purged. `Set.size` is therefore an **upper bound**, exact once purged. *Rationale: keep reads simple and O(1).*
|
||||
- **Purging is the creator's job.** No curator service, no catch-up by readers.
|
||||
- **No description** in the Participation for now. *(To be reopened when the need arises: whatever we put there would become public.)*
|
||||
- **Creator offline**: the Set does not move until they have processed their inbox. Accepted.
|
||||
|
||||
## What changes vs the current implementation
|
||||
|
||||
What exists today ([[knowledge_context-internals]] §participantCount) derives a `participantCount` **written by the owner** from inbox markers carrying the **plaintext `userId`**.
|
||||
|
||||
- **Drop the `userId`** from inbox deposits → only the **Participation's reference** remains.
|
||||
- **Count distinct people** through the discriminator above, no longer `userId`s.
|
||||
- **`event.participantCount` goes away**, replaced by `Set.size`.
|
||||
- **Identity resolution** now goes through **reading the profile** (hence through being connected), no longer through the marker.
|
||||
- **Withdrawal stops being a deletion** → `active` set to false + a purge by the creator. See [[caveat_participation-deletion]], whose requirement (« authoritative, must not come back ») still holds but changes mechanism.
|
||||
|
||||
Still valid as-is: **reactive reads**, **re-arming on reconnection**, and the **id-space fix** already shipped.
|
||||
|
||||
## Open points
|
||||
|
||||
- **Participation scope** — it becomes **public**, whereas current product doctrine places it in *protected* ([[knowledge_data-scopes-and-discovery]], concept `functional-domain`). That leaf describes **what is implemented**: do not change it until this brief has graduated, but **do update it at that point**.
|
||||
- **Recognition by connections** (step 7) — and what happens to a broken connection: the contract publishes **no revocation**, so sharing a profile is permanent. Explicitly deferred to a second stage.
|
||||
- **Public reads are not recursive** — this is the principle the whole model rests on, and it deserves to be stated on its own: *an item in the **public** store is public — whoever has the URL reads the content.* But **not recursively**: public content may **reference** private content, and **that is exactly our case**. So the creator reads the Participation (public) and **cannot** follow the reference to the profile (protected). That is what yields both readability by the creator and anonymity towards them — with no additional mechanism.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Blocking — a contract gap**: no published way to **dedup without reading** (see above). Until the contract answers it, coding this model would produce a count that **claims** to be a count of people without being one. Raise it with the provider; do not emulate it here.
|
||||
- **Parked**: **identity terminology** (wallet / user / profile) — see `.project/to-discuss.md`.
|
||||
|
||||
## Status: model settled, implementation gated
|
||||
|
||||
The model is **settled** (PO, 2026-07-27). What remains gated is the **implementation**, waiting on the dependency above. **Do not remove the current owner-derived counter** in the meantime ([[knowledge_context-internals]]).
|
||||
|
||||
Links: [[caveat_participation-deletion]], [[rule_document-per-entity]], [[rule_app-uses-sdk-surface-only]], app-security ([[brief_2026-05-18_authorization-matrix]], [[knowledge_trust-model]]).
|
||||
@@ -1,100 +0,0 @@
|
||||
---
|
||||
type: brief
|
||||
summary: One persisted shape holding on BOTH backends — NextGraph (per-document encryption) and ActivityPods (WAC) — references rather than embedded content, no stored counter, with the acl:Append behaviour and the deduplication gap left open
|
||||
---
|
||||
|
||||
# Brief (2026-10-03) — One data shape for two rights models
|
||||
|
||||
Festipod puts all its persistence behind interchangeable Refine backends (the seam's own contract is in code, `src/shared/refine/providers/types.ts`). Two are targeted: NextGraph plus its polyfill, and `@activitypods/refine-providers`, whose reconstructed observation is pinned beside this leaf ([[contract_activitypods-providers]]). The question this brief answers: what structure survives both rights models unchanged.
|
||||
|
||||
## The primitives, side by side
|
||||
|
||||
| What is needed | ActivityPods | NextGraph |
|
||||
|---|---|---|
|
||||
| Unit of rights | LDP resource + WAC | **document** |
|
||||
| List attached to a resource | `as:Collection` attached by a predicate, `semapps:dereferenceItems` | a Set inside the document |
|
||||
| Let a third party contribute | `acl:Append`, or `apods:PostOutbox` to the recipient's inbox | `inbox.postToDocument` |
|
||||
| Grant "my connections" | `acl:agentGroup` + a WAC group | per-document sharing, once per connection |
|
||||
| Name without granting access | reference + WAC refuses the GET | reference carrying no key |
|
||||
| Revoke | `pod-permissions.remove` exists | not published |
|
||||
| Write offline | no (client-server) | yes (local-first) |
|
||||
|
||||
## The design rule that follows
|
||||
|
||||
**The common denominator is NextGraph**, whose model is the strict subset: no groups, no revocation, sharing wholesale per document. So structure for NextGraph and ActivityPods will serve that structure — more cheaply even, with groups. The converse does not hold: any structure that needs a server-side projection or a revocation is untenable on NextGraph.
|
||||
|
||||
## The structure
|
||||
|
||||
```
|
||||
Event own document, public, written by its creator
|
||||
└─ participations an attached list of REFERENCES (never embedded content)
|
||||
Participation own document, owned by THE PARTICIPANT
|
||||
├─ event → ref
|
||||
├─ active → boolean
|
||||
└─ participant → ref to the Profile
|
||||
Profile own document, protected
|
||||
```
|
||||
|
||||
## Why references and not embedded content — three facts
|
||||
|
||||
1. **Ownership.** The participation must be writable by its participant and by nobody else (withdrawal must be authoritative — [[caveat_participation-deletion]]). On NextGraph write access is granted per document, so the participation **must be** a document; embedded in the event it would be writable only by the event's creator.
|
||||
2. **Per-reader variation is impossible inside a single document on NextGraph**, because encryption and sharing are per document. It is obtained by **indirection**: the reference is always present, and what varies is the ability to **follow** it.
|
||||
3. [[rule_document-per-entity]] already says this, and says it for exactly this reason.
|
||||
|
||||
## The non-visibility mechanism differs — PO precision, 2026-10-03
|
||||
|
||||
On NextGraph the target is **undecipherable** for want of a key: nothing is absent, the reference itself is readable. On ActivityPods it is either inaccessible (WAC refuses the GET) or the reference is omitted by server-side projection. Both land on the same application state: **a reference one may or may not resolve.**
|
||||
|
||||
## Consequence on the domain types
|
||||
|
||||
The type models the NextGraph shape, where everything is present:
|
||||
|
||||
```ts
|
||||
interface FpParticipationData {
|
||||
id: string;
|
||||
event: string;
|
||||
active: boolean; // NOT optional — the participation is readable by everyone
|
||||
participant: string; // NOT optional — a reference, which names without granting access
|
||||
}
|
||||
```
|
||||
|
||||
Resolution alone may fail: `resolveParticipant(ref)` yields `FpUserData | undefined`, where `undefined` means "not a connection". ActivityPods' omission is a **degradation the binding absorbs**: it reports "a participation whose participant does not resolve" — the same state as "I do not hold the key".
|
||||
|
||||
An error made in session and corrected here: `active?` and `participant?` were proposed first, which lifted the ActivityPods adaptation into the common model.
|
||||
|
||||
## The count
|
||||
|
||||
**No stored counter, ever.** The number of participants is `participations.length`. `knownParticipants` is the participations whose participant resolves — a presence test, not an access check. Withdrawal is `active: false` on one's own document.
|
||||
|
||||
## The three invariants that make the app platform-indifferent
|
||||
|
||||
1. One document per entity; never embedded content.
|
||||
2. A reference may be unresolvable, and that is a **normal state** — neither an error nor an absence (the app shows "someone").
|
||||
3. The list is an **upper bound that converges**; never assume it is complete at the instant (already documented by [[caveat_participant-count-one-connection-lag]]).
|
||||
|
||||
## Open points
|
||||
|
||||
### NOT VERIFIED — does `acl:Append` on a collection let a third party insert an item without being able to remove one?
|
||||
|
||||
WAC mode enforcement lives in `@semapps/webacl`, absent from the ActivityPods checkout consulted and not installed. The mode is real and genuinely used (`tests/apps/example.app.js` declares `accessMode: ['acl:Read', 'acl:Append']`), but its behaviour on a SparqlPatch `INSERT DATA` / `DELETE DATA` was not observed.
|
||||
|
||||
**The structure does not depend on the answer.** If Append works that way, the participant appends directly and the count is immediate. Otherwise the route is `apods:PostOutbox` to the creator's inbox, whose app adds the reference — which is exactly the NextGraph shape. Only the latency changes.
|
||||
|
||||
### OPEN — deduplication: neither platform counts people, and the implementation here does not either
|
||||
|
||||
[[brief_2026-07-20_attendance-set-model]] requires that the creator tell two references from the *same* person apart from two references from different people, **without knowing who** — otherwise the count is not a count of people and a participant can inflate it. **The code here does not do that** (verified 2026-10-05). A different problem is solved, and solved well: `materializeAttendance` (`src/shared/data/registration.ts`) keys its active set by a **per-deposit** `uid` minted from time plus randomness, so a broker re-sync replaying the same deposits converges instead of double-counting — that is **replay idempotence**, not person identity. The count is therefore a count of **deposits**: the same person joining twice counts twice. Three further findings about the current implementation:
|
||||
|
||||
- **The plaintext `userId` travels in the deposit**, and the cancellation fallback depends on it — a leave without a known `regUid` cancels the earliest still-active join carrying that `userId`, so N leaves cancel N joins. The attendance-set brief's own change *"drop the `userId` from inbox deposits"* was never made, so the creator **does** know who and the anonymity property does not hold today. The privacy-preserving discriminator was never needed because the privacy was never implemented.
|
||||
- **Participations live in the protected scope**, not public, and withdrawal is still a deletion ([[caveat_participation-deletion]]) — so the target model is not in place either. The attendance-set brief's own status line, *model settled / implementation gated*, still holds.
|
||||
- **The gap was never raised through the declared channel.** The five frictions in this app's polyfill declaration (`polyfill-surface/usage_festipod.md`) cover inbox idempotence, the absence of a push on one's own deposit, the reactive read not seeing one's own write, the impossibility of resetting the test wallet, and a wrong published signature. None asks for a per-person discriminator.
|
||||
|
||||
So the divergence is not "NextGraph has an upstream gap while ActivityPods does not": **both count deposits rather than people.** ActivityPods could arbitrate server-side because the server sees everything; NextGraph awaits a primitive. And the gap sits in **neither Refine provider** — it is in the polyfill on one side and the server on the other, which is what matters when deciding what to contribute where. The upper bound remains the common fallback position, already accepted by the PO.
|
||||
|
||||
## Two ActivityPods constraints not to rediscover later
|
||||
|
||||
- **The Refine providers cover CRUD only.** Creating the collection, setting WAC, creating a group, posting to the outbox are not in the data provider, which does not implement Refine's `custom` either — so there is no escape hatch through Refine and those calls happen beside it.
|
||||
- **A custom ontology prefix must be registered at prefix.cc**, the Pod provider requiring every ontology to have a known prefix; this concerns our `fp:`. Shape trees must also sit at a public URL, one per entity, since they cannot reference other shapes — no sharing cascade.
|
||||
|
||||
## Reservation to keep alive
|
||||
|
||||
The reference to the profile is readable by everyone and therefore collectable: it is a **correlatable pseudonym, not anonymity**, and must never be presented as such. The reservation comes from the attendance-set-model brief, and the 2026-10-03 precision reactivates it.
|
||||
@@ -18,26 +18,23 @@ Directives recorded at the resumption of the hand-off (`.project/handoff/refine-
|
||||
|
||||
Reading these at this stage is adoption-time reading, explicitly directed — the standing constraint against reading provider sources at work time is unaffected (`@activitypods/refine-providers` remains specified by its pinned reconstruction, `activitypods-providers/contract_activitypods-providers.md`).
|
||||
|
||||
- **Example apps** — `/home/sylvain/projects/reconnexion/welcometomyplace` and `/home/sylvain/projects/reconnexion/mutual-aid.app`: working integrations to mine for provider configuration, resources, and the on-behalf backend pattern.
|
||||
- **Example apps** — the reference apps under `~/projects/activitypods/` (`welcometomyplace`, `mutual-aid.app`, `portejunes`), the only allowed source of pod-interaction patterns (project rule `festipod-only-reference-app-patterns`).
|
||||
- **ActivityPods platform source** — `/home/sylvain/projects/activitypods/activitypods`; Semapps lives in a sibling folder.
|
||||
- **Shapes** — `/home/sylvain/projects/activitypods/shapes`: readily usable, and **evolvable by us** if Festipod's entities require it (that repo is ours to adapt).
|
||||
|
||||
## Constraints already on record (see the 2026-10-03 brief and the reconstruction)
|
||||
## Constraints on record
|
||||
|
||||
- `fp:` must be registered at prefix.cc; shape trees must sit at public URLs, one per entity, no sharing cascade.
|
||||
- A Festipod CLASS with its own shape tree needs `fp:` registered at prefix.cc: the pod registers the ontology of every class it creates a data registration for, and refuses one whose prefix it cannot find (`registerOntologyFromClass` in the pod provider). Shape trees must sit at public URLs, one per entity, no sharing cascade. A Festipod PREDICATE on an existing resource does not need it: the pod stored and returned a `http://festipod.org/` predicate on a profile, `fp` unregistered (verified live 2026-10-29: written with the app's token, returned under the full IRI).
|
||||
- The Refine providers cover CRUD only; `custom` is not implemented — no escape hatch through Refine.
|
||||
- `getMany` silently drops failed fetches — it erases the "unreadable reference" state the model needs (a candidate contribution).
|
||||
- `acl:Append` third-party insert-without-remove behaviour is NOT VERIFIED; the structure does not depend on the answer.
|
||||
|
||||
## Reconnaissance answers (2026-10-09)
|
||||
|
||||
- **On-behalf mechanism — ANSWERED.** An app backend is an ActivityPub actor (`@activitypods/app` `AppService`, Moleculer); it signs pod requests as the app actor and the pod impersonates the user after checking registration + grants. Frontend calls use the Solid-OIDC dual-identity token instead. No unattended per-user backend token exists.
|
||||
- **Registration/Participation — production precedent found.** welcometomyplace persists NO registration resource: a join is an `as:Join` activity posted to the user's outbox, the backend service handles it and adds the actor to the event's `apods:attendees` collection (attached via `attachPredicate`, `PodCollectionsHandlerMixin`); a leave is `as:Leave`, same path in reverse. Membership is read via `pod-collections.getItems`. mutual-aid uses none of this (comments, likes, announces only).
|
||||
- **Registration/Participation — production precedent found.** welcometomyplace persists NO registration resource: a join is an `as:Join` activity posted to the user's outbox, the backend service handles it and adds the actor to the event's `apods:attendees` collection (attached via `attachPredicate`, `PodCollectionsHandlerMixin`); a leave is `as:Leave`, same path in reverse. Membership is read via `pod-collections.getItems`. mutual-aid uses none of this (comments, likes, announces only). Festipod's adaptation, where participants must stay unidentifiable to non-contacts: [[decision_2026-10-29_participation-privacy-mechanism]].
|
||||
- **Event-in-event — feasible without touching any shape.** The `as/Event` and `as/Profile` SHACL shapes are open (no `sh:closed`), and the generic ActivityStreams vocabulary already defines `as:context`, `as:partOf`, `as:inReplyTo`. A meeting point is a plain `as/Event` carrying an `as:context` link to its parent event — the presence of the link is what distinguishes it, nothing else. Shapes are consumed for access needs and container setup, not server-side resource validation, so nothing breaks.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Participation topology — the one real divergence from the 2026-10-03 structure: welcometomyplace keeps the canonical list creator-side (an `apods:attendees` collection on the event, writes backend-mediated), where the two-rights-models structure makes each participation a participant-owned document. Both land on the same application state (a reference that may or may not resolve); the choice is who owns the write path. **Arbitration route decided 2026-10-09: the implementation plan evaluates both against the concrete screens (count, withdrawal, discovery, reference non-resolution) and submits an argued recommendation before anything is frozen.**
|
||||
- `as:Join` has a shape but no shape tree: if participations must be addressable as resources in access needs, adding `shapetrees/as/Join.ttl` for an already-existing AS type is the minimal move — or the collection pattern makes it unnecessary.
|
||||
- The backend's deployment shape (service alongside the app? a platform app?).
|
||||
- Whether the four pointed-to provider contributions (from the hand-off) are still the right set once the backend exists — some may move from "contribution to the providers" to "our backend's job".
|
||||
- Whether the three pointed-to provider contributions (from the hand-off) are still the right set once the backend exists — some may move from "contribution to the providers" to "our backend's job".
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
type: caveat
|
||||
summary: Several coherence-pass features were built and unit-tested but never played against a real pod — invitations, image upload, bio/city/photo round trip, profile completion — plus a few known limits of the read side
|
||||
last_checked: 2026-10-21
|
||||
---
|
||||
|
||||
# Caveat: built but not verified on a real pod
|
||||
|
||||
Unit and UI-layer tests are green; none of the following has run against a live ActivityPods stack. Treat as unverified, and re-check at the first run on a pod:
|
||||
|
||||
- **Invitations**: that the `Announce` is delivered to the chosen contacts' Pods.
|
||||
- **Image upload** ([[decision_2026-10-21_images-are-uploaded-to-the-pod]]): container resolution, the `Location` header, the public-read grant, and the re-consent for the File access need.
|
||||
- **Profile round trip**: bio, city and photo (`image`) written and read back through the provider.
|
||||
- **Profile completion**: the onboarding gate on a pod whose profile has an empty name; a pod linking no profile at all only gets a message, since creating and linking an `as:Profile` is outside the pinned contract.
|
||||
|
||||
Known limits of the read side, by design or by backend: catalogue entries carry no participant count (so cards of events never opened show none, and gain one once opened); an empty catalogue is indistinguishable from an unreachable one; another person's events are not listable (`getUserEvents` answers for the signed-in user only).
|
||||
@@ -31,8 +31,20 @@ pod provider 3000 (OpenID + `/auth` signup/login), pod provider frontend 5000, F
|
||||
|
||||
On a fresh pod, an `as:Event` POST lands at the pod root (`/alice/data/<uuid>`): typed containers such as `/alice/data/as/event` exist only after a user installs an app whose access needs declare that shape tree. Do not expect typed containers before app registration.
|
||||
|
||||
## Data location (hard-won, 2026-10-26)
|
||||
|
||||
- **Fuseki's data dir must stay on the SSD** (`/home`, NVMe). Measured: a signup is ~10 s on the SSD, 150–200 s on the spinning HDD (`/hdd-home`) — TDB2 fsyncs per write and the seek time dominates. The HDD mount also hosts the bulk of the host's files; keep fuseki off it.
|
||||
- **Never replace `data/fuseki` with a symlink after the container exists.** Docker resolves the bind source when the container is CREATED; moving the data away and leaving a link behind leaves the running container with a broken/empty mount (symptom: signup 500 « Error when creating secure dataset … FileNotFoundException: /fuseki/system_files/… »). `docker restart fuseki` re-resolves and heals — until the next behind-its-back move.
|
||||
- The e2e suites delete the accounts they create at the end of every run (user decision 2026-10-26): `DELETE http://localhost:3000/.account/:username` with the user's token (a user may delete only their own account). The platform tombstones the account, sends the Delete activity, and drops the fuseki dataset on a delay — so test data no longer accumulates and the periodic full wipe is no longer needed. `diag-invite.ts` is the only suite left without cleanup (manual diagnostic).
|
||||
|
||||
## Backend fresh-boot note
|
||||
|
||||
The Festipod backend has its OWN datasets, `festipod` (main, created SECURE at first boot — WebACL is on) and `settings-festipod` (accounts), named like the sibling apps' (`welcometomyplace`/`settings-wtmp`…). Never point it at the pod provider's `settings` dataset, and never delete or recreate `settings`: it holds the pod provider's accounts. A backend dataset reset follows the compose file's header (delete the datasets and the secure dataset's files on disk, empty the backend's Redis cache database). After a reset, pod accounts that had installed the app must install it again: the new backend knows none of their registrations.
|
||||
|
||||
On a FRESH backend dataset (after a wipe), the app's actor and its access-need group are created in parallel by the mixin's boot and can race: the actor can end up without `interop:hasAccessNeedGroup` (symptom: `GET /app` links a group that 404s; consents register zero grants). `backend/services/app.service.js` heals this at boot by polling for the group (up to 60 s) and attaching it. If the backend is restarted while its dataset is wiped, wait for the heal before running consented flows — or simply re-check `GET /app` links a group that resolves 200.
|
||||
|
||||
## Teardown
|
||||
|
||||
`pkill -f moleculer-runner; pkill -f react-scripts`, then `docker compose down` in `pod-provider/`. Data persists in `pod-provider/data/` (gitignored); delete that directory to fully reset.
|
||||
`pkill -f moleculer-runner; pkill -f react-scripts`, then `docker compose down` in `pod-provider/`. Data persists in `pod-provider/data/` (gitignored); delete that directory to fully reset. With the suites cleaning up after themselves (above), a full reset should now be a rare event, not a maintenance ritual.
|
||||
|
||||
Current stack test account: `alice` / `Test1test` on localhost:3000.
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
type: decision
|
||||
summary: Festipod keeps no friend model; contacts are the Pod's own apods:contacts collection, a contact request is an Offer{Add{my profile}} posted from the browser to my own outbox, invitations are Announce{event} activities, and nothing is built for acceptance or push
|
||||
---
|
||||
|
||||
# Decision (2026-10-21): contacts are the Pod's social graph
|
||||
|
||||
## Decision
|
||||
|
||||
- **No home-made friend model.** A user's network is the `apods:contacts` collection linked from their actor document (the app falls back to the profile record), managed by the Pod — mutual when both went through the request/accept flow, though not guaranteed (see the platform defects below). In the app, `friendships` is only a mirror of that collection and `getFriends` reads it. Contacts are resolved to profiles through the same path as event participants.
|
||||
- **Contact request** (`addFriend`): an `Offer{ object: Add{ object: { id, type: 'Profile' } }, to, target }` addressed to the other person's actor, posted to the requester's **own outbox with their own token**, from the browser (`src/shared/data/contacts.ts`). The `type: 'Profile'` is embedded in the activity: the platform's `CONTACT_REQUEST` matcher requires it, and it must not dereference the profile — a protected profile 403s anonymously and a bare-URI object was silently ignored (fixed 2026-10-22). The recipient lands it in `apods:contactRequests` and accepts on their Pod provider's own network page. **Festipod builds no acceptance screen.**
|
||||
- **Sharing my connection** (the primary flow — see [[decision_2026-10-22_connection-sharing-is-the-invite-capability]]): an **invite capability** (VerifiableCredential) issued by the Pod (`POST {webId}/vc/v0.3/credentials/issue`), shared as `{frontendUrl}/invite/{capability}`; the recipient's contact request carries a VerifiablePresentation of it and is **auto-accepted** by the inviter's Pod. Strictly better than the bare request: no manual acceptance, and the invitee sees the inviter's profile (name, photo) through the grant.
|
||||
- **Invitation to an event** (`inviteToEvent`): an `Announce{ object: <event>, to: [chosen contacts] }` posted the same way. The invitable set is the real contacts only.
|
||||
- **No backend service added.** A user-initiated request needs nothing the browser cannot do; a backend handler (notifications for people without the app) would be speculative without a pod to test it on. Push notifications stay the Pod provider's job.
|
||||
- Providers with no Pod (the disconnected demo, the suspended NextGraph path) **reject** `addFriend` and `inviteToEvent` instead of simulating state.
|
||||
|
||||
## Channels
|
||||
|
||||
Participations are **public objects** (anyone sees that there are participants), but the **identity link** is protected — the profile is readable by contacts only, and the carved rule [[behavior_participation-listing-is-contacts-only]] reserves listing a person's events to their contacts, for every client. How contacts recognise participants and list a contact's events is [[decision_2026-10-29_participation-privacy-mechanism]]; the app reads no one else's outbox.
|
||||
|
||||
## Consequences
|
||||
|
||||
- "Demande envoyée" is session-local: the target's request collection is not readable by the sender, so after a reload the button offers the request again.
|
||||
- There is no `removeFriend`.
|
||||
- The `apods:contacts` list is a display, not a grant: the pod adds the sender of a received `Accept` of a contact request without checking a request was sent (a sender whose profile it cannot read is turned away; one who first sent a request of their own is added — verified live 2026-10-29), and keeps a removed contact in the `/contacts` WAC group (both platform defects reported upstream 2026-10-29). Festipod never derives a read right from the list — rights follow the group, see [[decision_2026-10-29_participation-privacy-mechanism]].
|
||||
- The request/accept round trip is verified live by the rights matrix (2026-10-29): the request posted from the requester's outbox, its acceptance naming the stored `Offer`, both lists then naming each other.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
type: decision
|
||||
summary: Images (event cover, profile photo) are uploaded as binary LDP resources to the Pod's file container from the browser, then made publicly readable; the URL is stored in coverImage / photo; existing users must re-consent for the new File access need
|
||||
---
|
||||
|
||||
# Decision (2026-10-21): images live in the user's Pod
|
||||
|
||||
## Decision
|
||||
|
||||
- `useUploadImage` (`src/shared/hooks/`) resolves the Pod's `file` container, POSTs the file binary with the user's token and reads the new URL from the `Location` header, then calls `grantPublicRead` (`src/shared/utils/`): a best-effort WAC ACL PATCH granting `foaf:Agent` read. Without the grant, an image nobody else can read is a dead feature. Without a session (the demo) the upload rejects.
|
||||
- The URL is stored as `coverImage` on an event and `photo` on a profile. On ActivityPods the cover maps to the AS2 term `image` and the profile photo to `vcard:photo` — the term both reference apps read (mutual-aid, welcometomyplace), after verifying the `vcard:` prefix is present in the platform context. Interop cross-apps : une photo stockée sur un autre vocabulaire serait invisible partout.
|
||||
- The app declares the `shapetrees/File` access need (read + write) in `backend/services/app.service.js`. **Users who registered the app before this change must re-consent** for uploads to be allowed.
|
||||
- `resolveContainerUri` and `fetchJson` come from `@activitypods/refine-providers/utils`, which the pinned contract does not list: this use is outside the contract and must be declared in the usage declaration / raised to the provider.
|
||||
- The event cover falls back to a neutral gradient; the old stock-photo map is gone.
|
||||
|
||||
## Consequences
|
||||
|
||||
Covers and avatars are visible to anyone who can read the event or profile record, as the `grantPublicRead` makes the file itself public. Never verified end to end on a real pod — see [[caveat_t06-unverified-on-a-real-pod]].
|
||||
@@ -55,9 +55,6 @@ Mutations on the create/participate path **reject** rather than returning quietl
|
||||
A `Participation` written **today** carries the profile document's NURI in `fp:user`, so the direct join `u.id === userId` matches. Participations written under the **earlier** scheme carry `urn:festipod:user:<normalized-handle>`, which matches nothing directly.
|
||||
|
||||
**`resolveParticipantUser`** is the single join point and tries, in order: (1) the direct id match — today's writes, and the demo seed's bare `user-1` space; (2) failing that, strip `USER_PRINCIPAL_PREFIX` and compare the remainder to `normalizeIdentifier(profile.username)`. Never join by direct comparison at a call site: getting it wrong renders every participant as « participant inconnu », which shipped once. `USER_PRINCIPAL_PREFIX` is **read-side only** — nothing mints it any more; it is not a shape to write against. The inbox deposit `uid` (`mint…`) is a third space that takes **no** part: it identifies a deposit for the counter, never a user.
|
||||
|
||||
> **Horizon.** The target model drops the plaintext `userId` and resolves identity by reading the profile — [[brief_2026-07-20_attendance-set-model]], gated. The id-space fix is noted there as still valid: do not undo it in anticipation.
|
||||
|
||||
## Reads = `watchShape`, writes = an optimistic overlay
|
||||
|
||||
Reads go through `useShapeQuery(shape, scope)` — three scoped reads (events/public, profiles/protected, participations/protected) mapped by `shapeAdapters.ts`; `ready` combines their `isSuccess` flags. The app resolves, lists and re-queries nothing ([[rule_document-per-entity]] §Reads).
|
||||
@@ -90,6 +87,10 @@ Two measurement points are laid down **as a pair**: the owner's materializer log
|
||||
|
||||
The app settles its identity once, before anything renders, and offers no way to change it (`app-security` → [[decision_2026-08-10_the-barrier-names-no-identity]]). One page hosts exactly one identity for its whole life, so there is no identity-change reset: no `useEffect([identifier])`, no cap reset, no registry-cache reset. Do not reintroduce a reset for a transition that cannot happen. Cross-identity **isolation** is still a real requirement, but proving it needs two genuinely separate browser contexts (`bdd-testing` → [[rule_tests-validate-festipod-not-the-sdk]]).
|
||||
|
||||
## On ActivityPods the context is `refineData.tsx`, and read-your-writes is confirmed by a collection
|
||||
|
||||
The ActivityPods implementation of the same context (`src/shared/context/refineData.tsx`) holds a join or leave as a pending act on top of the reads and releases it only when a read issued after the act confirms it — the person's own participations collection for membership, the meeting point's attendee list for the count — or when a bounded re-read schedule runs out (verified in code). A read that merely shows the asserted state is not a confirmation: it may predate the act. Details: [[decision_2026-10-29_participation-privacy-mechanism]].
|
||||
|
||||
## Mutations are no-ops in local mode
|
||||
|
||||
In local/demo mode (`useLocalData`), `createEvent`/`joinEvent`/`leaveEvent`/`updateEvent` are **no-ops** (a log, no state change) — yet the screens still show a success toast. Misleading UX, unchanged. See [[knowledge_data-modes]].
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
type: knowledge
|
||||
summary: The Fp* app types and their SHEX shapes — Event (no host), UserProfile, Participation, MeetingPoint and Notification are persisted, Friendship stays local-only; the generated ORM names carry NO Fp prefix and are aliased at the import sites
|
||||
summary: The Fp* app types and their SHEX shapes — Event (no host), UserProfile, Participation, MeetingPoint and Notification are persisted, Friendship has no shape of its own; the generated ORM names carry NO Fp prefix and are aliased at the import sites
|
||||
last_checked: 2026-08-17
|
||||
---
|
||||
|
||||
@@ -11,11 +11,13 @@ last_checked: 2026-08-17
|
||||
| Type | Persistence | Key fields |
|
||||
|---|---|---|
|
||||
| `FpEventData` | SDK (Event shape) | title, date, startDate, endDate, startTime, endTime, location, distance, participantCount, coverImage |
|
||||
| `FpUserData` | SDK (UserProfile shape) | name, initials, username, role, isPublic |
|
||||
| `FpUserData` | SDK (UserProfile shape) | name, initials, username, role, isPublic, bio, city, photo (all optional; on ActivityPods `photo` is the AS2 `image`) |
|
||||
| `FpParticipationData` | SDK (Participation shape) | event + user + isConfirmed |
|
||||
| `FpMeetingPointData` | SDK (MeetingPoint shape) | event, host, title, place, time |
|
||||
| `FpNotificationData` | SDK (Notification shape) | recipient, type, ref, payload, timestamp, isRead |
|
||||
| `FpFriendshipData` | **local-only** | userId + friendId |
|
||||
| `FpFriendshipData` | **derived** on ActivityPods (mirror of the Pod's `apods:contacts`, see [[decision_2026-10-21_contacts-are-the-pod-social-graph]]); absent elsewhere | userId + friendId |
|
||||
|
||||
**On ActivityPods the participation is not a document of its own.** A sign-up is a member URN in the meeting point's `apods:attendees` collection plus the meeting point's URI in the person's participations collection (linked from the profile as `http://festipod.org/participations`); the person's `http://festipod.org/participationSecret` on the profile is what lets their contacts recognise the URN. No shape describes any of these — see [[decision_2026-10-29_participation-privacy-mechanism]] and `src/shared/data/participationPrivacy.ts` (verified in code).
|
||||
|
||||
**An event has no host.** `hostName`/`hostInitials` are gone from the type and the shape alike — the event is only the anchor, and the host lives one level down on the meeting point (`FpMeetingPointData.hostId`, SHEX `fp:MeetingPoint.host`). See concept `functional-domain`, [[knowledge_actors-and-concepts]].
|
||||
|
||||
|
||||
Reference in New Issue
Block a user