Skip to content

Latest commit

 

History

History
2295 lines (2185 loc) · 134 KB

data-model.md

File metadata and controls

2295 lines (2185 loc) · 134 KB

Data model in the pod

Solid Memo keeps everything a learner makes and studies in their own Solid Pod, as linked data files in one folder, the instance. This page says which file holds what, how the app finds the files after a login, and how it writes them without losing a change made on another device.

The code is in packages/solid/src/: the vocabulary in vocab.ts, discovery in typeIndex.ts. The app reads and writes the pod by the Solid Protocol, and finds Solid Memo's data through the type indexes, an editor's draft (standards.md).

Vocabulary and shapes

Solid Memo mints its own terms under https://solid-memo.com/ns/vocab/v1.ttl# (prefix sm: below); no existing RDF vocabulary covers spaced repetition. ns/vocab/v1.ttl defines them (vocab.md), and a SHACL shape under ns/shapes/ says what a valid subject of each class looks like, version by version (shapes.md). The site publishes both, and the app's constants, record types and descriptors are generated from them. Readers ignore unknown triples, and writers never delete triples they don't understand.

Every subject Solid Memo writes carries sm:formatVersion. A subject with neither that stamp nor a Solid Memo class is another app's, unless it's the catalog or a subject of Solid Memo's names it as its creator, publisher or distribution. Another scheduler's review state is another app's too. The data check only warns about them (validation.md).

flowchart LR
    accTitle: From pod data to the domain model
    accDescr: A subject is read as a versioned shape record, migrated to the latest record and mapped to the domain model, and a model is written back the same way in reverse.
    thing["Subject<br/>(client/rdf.ts)"] -->|readVersioned| record["shape record<br/>e.g. CardV1"]
    record -->|migrate| latest["latest record<br/>CardV2"]
    latest -->|cardFromRecord| model["domain model<br/>Card"]
    model -->|cardToRecord| latest
    latest -->|recordThing| thing
Loading

Discovery chain

flowchart LR
    accTitle: The discovery chain
    accDescr: From the WebID, the app follows the storage and the private and public type indexes to the instance container, and from the instance's folder to the rest of its data.
    W[WebID] -->|pim:storage| S[Storage root]
    W -->|solid:privateTypeIndex<br/>directly and via pim:preferencesFile| PTI[Private type indexes]
    W -->|solid:publicTypeIndex| PUB[Public type indexes]
    PTI -->|solid:TypeRegistration<br/>forClass sm:Instance| I1[Instance container]
    PUB -->|solid:TypeRegistration<br/>forClass sm:Instance| I2[Instance container]
    I1 -->|the folder's layout| D1["catalog.ttl, decks/, reviews/,<br/>history/, drafts/"]
    I2 -->|the folder's layout| D1
Loading
  • Storage: pim:storage triples in the (extended) profile. That's the WebID document and the documents it names as more of the profile (rdfs:seeAlso, foaf:isPrimaryTopicOf, foaf:primaryTopic). The WebID document is read under PROFILE_LIMITS, and the others under them all together, no more than MAX_PROFILE_DOCUMENTS of them (readLimits.ts). Else the Solid Protocol's Link-header walk-up from the WebID URL (rel="type" targeting pim:Storage, capital S), which asks the WebID document and its nearest MAX_STORAGE_ANCESTORS (8) containers (solidStorageGateway.ts); else a URL typed by hand. 0, 1 or N storages are handled.

  • Instances: one solid:TypeRegistration per instance, solid:forClass sm:Instance, in the type index the user chooses (below), its dcterms:title naming the instance (harmless extra triples): the only registration Solid Memo reads to find its instances. Reading accepts solid:instanceContainer or solid:instance naming an http(s) address with no query, fragment, dot segment (.., %2e%2e in any case) or empty segment (//; isInstanceAddress in instanceLayout.ts). The address is taken as written: another spelling of a folder (its host's case, a name outside ASCII) is that folder (below). An instance created, attached by URL or moved to from a guest's pod is registered at its address as a request sends it (instanceAddressOf): HTTPS://Pod.example:443/kortlekar-å is https://pod.example/kortlekar-%C3%A5/. An address that isInstanceAddress refuses as a request sends it isn't an instance to attach (notAnInstanceNoMeta). An instance with no title is named after its folder, with its percent-encoding undone; a name whose escapes don't decode, such as caf%E9, is shown as written (lastPathSegment in urls.ts). A registration that still can't be read as an instance is left out, and the rest of the list still loads. An index, a preferences file or an extended profile counts as none only when it isn't there (404, 410), can't be parsed or goes past the read's limits, even before it's sent (readsAsNone in datasets.ts). One outside the profile's own places, or past the MAX_PROFILE_DOCUMENTS a profile is read in, isn't read at all and holds none either. One that can't be read right now fails the list. That's a refusal (401, 403), any other status, no answer in time (podNoAnswer) or any other of the app's errors, an abort whatever its reason, no answer at all, or an error caused by one of these. An address the app doesn't send the user's login to (credentialsRefused), such as an index whose path names another server, fails the list too, each time it's read, until the link to the index is fixed. An access token may expire while the app is in the background, or a pod may be slow to answer. A list read again then must not come back empty, which would offer to create an instance the user already has. The app keeps the list it read before, and shows the error only when it has none. A type index is data another app may have written, and every instance listed is read. So the app follows the first MAX_CATALOG_LINKS (1,000) instances of all the indexes, the private ones first, and the list says when it is that long.

  • The rest of an instance's data has no registration: the catalog, the decks, cards, review states, answers and drafts are reached from the instance, at the places its folder's layout gives them (Instance layout). Earlier versions of the app wrote one registration per class of that data beside the sm:Instance one (examples below). The app no longer writes them, and still recognizes them: removing or deleting an instance removes them, renaming it retitles them, and the user can remove them from Preferences, keeping the instance.

  • Writing a type index saves it with If-Match the version read; on a 412 it tries again, three attempts in all (changeIndex in typeIndex.ts). The registration is added only when no equal one is there: sm:Instance, naming the container under either predicate, with or without its trailing slash (addInstanceRegistration). typeIndex.integration.test.ts reads the registration back from real servers.

  • Type index links are read from the WebID subject in the WebID document and in every extended profile document (rdfs:seeAlso / foaf:isPrimaryTopicOf), and private ones in the pim:preferencesFile too, where the Type Indexes specification keeps them. A public link in the preferences file is left out: the file is private, so no other app finds it there. A pod made long ago may link several indexes of a kind, such as one an app wrote at /settings/privateTypeIndex and one the preferences file names at /settings/privateTypeIndex.ttl. So every link is kept, each kind's once by address and no more than MAX_PROFILE_DOCUMENTS of them (locateTypeIndexes). Only the documents on the WebID's origin, on its document's origin or in a storage the profile names are read; a link to one anywhere else is left alone (boundaries.md). The preferences file is read only in one of the user's own storages, those their profile names (pim:storage) or else the one their WebID is in, or in those places when no storage is found. Each is read under PROFILE_LIMITS, no more than MAX_PROFILE_DOCUMENTS extended profile documents: a WebID document past them fails the lookup, and any other is left out. An index outside the user's own storages may be someone else's, even on the WebID's origin, since one server may keep many users' pods on it. So the app leaves a link to it out: nothing in it is read or written, no instance it registers is listed, and the user may create their own. Such a server shows each user's storage. When the storage lookup fails or finds none, the app still reads every index linked in the profile's own places, and lists the instances they register, but writes less:

    • When the WebID leads to no storage, the app writes only to an index in the WebID's own pod: the folder of the WebID document, or the folder above it when that's profile/. Only such an index is chosen by kind, accepted by its address, registered in, retitled on a rename or cleaned of an instance's registrations.
    • When the lookup fails, the app writes to no index. Choosing one to register in, retitling an instance's registrations and removing them fail as the lookup did, and work when it works again.
  • Missing indexes are normal on Community Solid Server pods. The app warns the user, who chooses to create the private index (a document under <storage>settings/ plus a profile link) or to register publicly. A kind counts as missing when no index of it is there or readable by the user (401, 403 count as not readable); any other failed read fails the choice. A public index the app creates is made readable by everyone with the public-read grant, as a published release is (boundaries.md). Other apps then find what it registers. When the grant fails, the index is kept as it is, and the choice says no one else can read it. The index goes in a storage the WebID leads to (never one typed by hand): the instance's, else the first. It never goes on the server of an instance elsewhere (attached by URL, or in a storage typed by hand). Without such a storage the index isn't created (typeIndexNoStorage, ownStorageFor in typeIndex.ts). The link goes in the WebID document when it's writable, else in the first extended profile in one of the user's own storages that accepts it (on Inrupt PodSpaces the WebID document on id.inrupt.com is read-only, and <storage>profile is writable). A document already at the target URL is adopted when it's typed solid:TypeIndex (notATypeIndex otherwise), not overwritten, and who may read it is left as it is: only an index the app writes gets the public-read grant. If registration fails, instance creation fails loudly, with no local fallback, and the new container is cleaned up. An instance is registered in the index the user chose, and in no other.

  • An index entered by its address must be in one of the user's own storages, those their profile names (pim:storage) or else the one their WebID is in (typeIndexOutsidePod), linked from the profile or not. The WebID's origin isn't enough: one server may keep many users' pods on it. Without a storage, the WebID's own pod stands in, as above. One the profile links is used as it is. Any other must also be readable by the user and typed solid:TypeIndex (notATypeIndex). The app finds its instances only in the indexes the profile links, so it then links this one from the profile: as public when it's typed solid:ListedDocument, as private otherwise (adoptTypeIndex).

  • Deleting an instance deletes what Solid Memo wrote in its container and nothing else (deleteInstanceData in instanceData.ts). Then it removes its registrations from every type index of the user's: its sm:Instance one and any an earlier version wrote for its data (below). In order:

    1. each deck's cards and reviews documents as the catalog names them, if they're the deck's: they say so, or they're in the instance's own folder (below). A release (a document whose <> is an sm:Deck) or a draft's document is never a deck's, wherever it is, and nothing in it is removed;
    2. the answer log's months (history/<YYYY-MM>.ttl), as history/ itself lists them;
    3. the drafts the catalog links that are in the instance's drafts/ (Drafts and releases);
    4. preferences.ttl, palettes.ttl, digest.ttl and catalog.ttl, in that order, so a failed delete can be retried and find the decks and drafts again. A catalog the pod serves but that can't be read is kept, with the decks' documents and the drafts; the rest goes;
    5. decks/, reviews/, history/ and drafts/, each only if then empty;
    6. meta.ttl, last of the documents, so a half-deleted instance still attaches by URL;
    7. the container, only if then empty.

    From each document only what's Solid Memo's of its kind is removed (Write discipline, removeOwned):

    • a deck's cards, their distractors, its review states and the document's saying it's the deck's;
    • a month's answers (sm:Answer);
    • the preferences (sm:Preferences);
    • the palettes (sm:Palette, sm:ColorSet);
    • the digest's receipts, schedules and month summaries;
    • the catalog's subjects (the catalog, its decks, groups, agents and distributions);
    • the instance's #it;
    • a draft's subjects and what they lead to.

    A document holding another app's subjects too is kept with those alone, and the result names it (keptDocuments), for an instance registered at the pod's root too. A document's ACL goes with it (the Solid Protocol has the server delete it). A document that's missing, or goes before the delete, counts as deleted.

    Anything else in the folder is another app's, and kept, as is every container on the folder's path. The releases published from the instance, which others may have added by their address, are kept too: those in releases/, those the catalog links (sm:publishedRelease) in another folder of the instance, and any the catalog names as a deck's document. A notice (KeptFolderNotice) links the kept folder, says why it was kept (another app's files, or the releases, keptReleases) and how many documents were kept for another app's data. The delete's confirmation says both are kept. Data goes before registration, so a failure leaves the instance listed and the delete retryable.

    Every blocking server the end-to-end tests start (testing.md), and Pivot and Community Solid Server 8 (with LWS too), keep another app's file and its folder, and delete a folder holding only Solid Memo's documents with its access rules (foreignData.integration.test.ts). Solid-Nextcloud lists a folder's ACL among its contents, so there such a folder is kept, its access rules in it. What the advisory servers fail, and why, is in interop.md; this one is nc-acl-member.

    Only an instance in the user's own storages (what discoverStorages finds, isInStorages; a folder entered by hand isn't one) has its data deleted. Any other is someone else's, or a server's that may refuse or be gone: the picker doesn't offer the delete and says why, and the use case refuses it (instanceOutsideStorages) with nothing sent there.

  • Removing an instance from the list (detachInstance) removes its registrations from every type index of the user's, as deleting does (below), and nothing else. An instance found in any of them is removed from all of them. It reads and writes only those indexes, so no request goes to the instance's server and it works whatever that server answers. Each index is tried whatever the others answer, and one that's missing has nothing to remove; a failure is reported once both were tried, and the list is read again either way.

    The picker offers it for every instance but a guest's own, which is on no other server and can only be deleted; the use case refuses to remove that one too. The data stays where it is, and attaching by its address brings the instance back; a new instance in that folder is refused (instanceAlreadyThere).

    Once it's gone from the indexes, this page's credential gate no longer counts the folder as the user's, so reads there go as no one and writes are refused. A folder the user entered by hand still counts until the page reloads, as does the folder in another open tab. An instance's meta document is always read as the user, but once the instance is off the list, only attaching it again reads that document.

Choosing a type index

Creating an instance, adding one by its address or moving a guest's study offers every type index of the user's they can read now (getRegistrationOptions, readTypeIndexChoices in typeIndex.ts), ranked (rankedFor in typeIndexChoice.ts). One that isn't there, or that the user may not read (401, 403), isn't offered. Any other failed read (a timeout, a server error) fails the choices, as it may work when tried again: an index left out for it would be offered as one to create. Each index of a kind is ranked in this order:

  1. one that already holds a Solid Memo instance;
  2. the one the preferences file links (private only);
  3. one typed as its kind (solid:UnlistedDocument for private, solid:ListedDocument for public) before one that says neither;
  4. otherwise by address, never by the order of a profile's triples.

Three things move an index to the end of its kind. From last: a type that says it's the other kind, a document linked as both kinds, and a public index no one else can read. The best private index is preselected as Recommended (RegistrationTargetChooser.tsx). A kind the user has none of is offered as one to create. The user may enter any other type index of theirs by its address (above). A target of a kind alone ("private", "public") registers in the best index of that kind, or creates one (ensureTypeIndex).

Each index is also read as no one (HEAD, readableByAnyone), and the chooser says what may make it the wrong one:

  • a public index no one else can read: other apps don't find what it registers;
  • a private index anyone can read: everything it registers can be seen by anyone;
  • an index typed as the other kind;
  • one document linked as both kinds, offered once: who may read it is unclear.

Each public choice says what public means: anyone can see that the instance exists, its name and where it is, and who can open it is still decided by its access settings.

Registrations

In the type index, the instance's one registration, by which Solid Memo finds it:

<#sm-inst-9f3c1a> a solid:TypeRegistration ;
    solid:forClass sm:Instance ;
    solid:instanceContainer <https://pod.example/solid-memo/main/> ;
    dcterms:title "Japanese study" .

Earlier versions of the app wrote one more for each class of the instance's data, titled with the instance's name, so a pod may still hold them. Each index that registered the instance got dcat:Catalog naming catalog.ttl#catalog, sm:Deck naming catalog.ttl (both with solid:instance) and sm:Card naming decks/ (with solid:instanceContainer). The private index alone got sm:ReviewState naming reviews/, sm:Answer naming history/ and sm:Deck naming drafts/. Their ids start #sm-cat-, #sm-deck-, #sm-card-, #sm-review-, #sm-answer- and #sm-draft-:

<#sm-card-7a21d9> a solid:TypeRegistration ;
    solid:forClass sm:Card ;
    solid:instanceContainer <https://pod.example/solid-memo/main/decks/> ;
    dcterms:title "Japanese study" .

meta.ttl makes a container self-describing: attach-by-URL reads it to recover an instance that lost its registration. Deleting an instance, or removing it from the list, removes the sm:Instance registration by its container, and each one an earlier version wrote by the exact IRI it names (<container>catalog.ttl#catalog, <container>catalog.ttl, <container>decks/, <container>reviews/, <container>history/, <container>drafts/). None is removed by what lies under the container, where another app may have registered its own data. A registration that registers something else too keeps it, and loses only the link to the instance's data. Those an earlier version wrote for an instance whose sm:Instance registration went some other way stay, as the app no longer lists that instance to remove.

From Preferences, the user can remove those an earlier version wrote for the open instance on the list, keeping the instance. "Old registrations" is offered when an index holds any, never to a guest and never on its own (removeOldRegistrations in typeIndex.ts). It reads and writes only the user's own type indexes, and takes a registration for one of the app's old ones only when all of these hold:

  • it's a solid:TypeRegistration for one of the classes above;
  • it names that class's exact IRI for this instance, under either predicate;
  • its id is in the index document, with a fragment that starts with that class's prefix and a dash, such as #sm-card-.

A registration that names the same IRI under another id stays: it may be another app's. An sm:Instance registration is never removed or changed, even one that also registers a class above. A registration that names something else too loses only the link to the instance's data. Each index is written once, with If-Match as above, and only when it holds one. An index that can't be read is said to be so, and isn't written.

Instance layout

<storage>solid-memo/<name>/          (default path; user-editable)
├── meta.ttl        #it: a sm:Instance; dcterms:title; dcterms:created;
│                        on an instance an earlier version's format
│                        update made, dcterms:replaces and
│                        dcterms:modified, ignored and kept;
│                        sm:formatVersion 2
├── preferences.ttl #it: a sm:Preferences (created with the instance,
│                        FSRS-6 its scheduler; an instance made before
│                        has none until its first save, and reads as
│                        SM-2): study caps, sm:answerScale,
│                        sm:developerMode, sm:invalidDataPolicy, sm:theme,
│                        sm:studyScheduler (sm:sm2 or sm:fsrs6),
│                        sm:desiredRetention,
│                        sm:schedulerInvitationDismissed, sm:palette
│                        (a concept of sm:Palettes, or another IRI,
│                        kept), sm:textSize, sm:formatVersion 6;
│                        whether logging in skips the Connected
│                        screen (sm:connectedScreenSkipped true,
│                        outside the shape)
├── palettes.ttl    the palettes the user designed, if any: one
│                        sm:Palette per palette (#palette-<id>),
│                        dcterms:title, sm:basedOn, sm:lightColors and
│                        sm:darkColors, its sm:ColorSet subjects beside
│                        it (#palette-<id>-light, #palette-<id>-dark),
│                        a #rrggbb color for each role it sets;
│                        sm:formatVersion 1 (docs/theme.md)
├── catalog.ttl     one subject per deck (titles live ONLY here), a
│                        sm:Deck and dcat:Dataset: sm:formatVersion 6,
│                        dcterms:description, sm:studyDirection, optional
│                        dcterms:creator/license, dcat:theme,
│                        dcat:keyword (language-tagged),
│                        prov:wasDerivedFrom, the deck's own study caps
│                        (sm:deckNewCardsPerDay/MaxReviewsPerDay), and
│                        for a course the chapters completed
│                        (sm:completedChapter); the language its
│                        card text (and a course's text) is shown
│                        in first (sm:deckCardLanguage, outside the
│                        shape); the hosts whose pictures it shows
│                        (sm:deckPictureHost, outside the shape);
│                        beside each deck its
│                        dcat:Distribution (#deck-X-cards) and the
│                        foaf:Agent nodes of its creators (#agent-…);
│                        and the deck groups (#group-…), a sm:DeckGroup
│                        and dcat:Catalog each: sm:formatVersion 1;
│                        on the catalog, its drafts (sm:releaseDraft)
├── decks/<deckId>.ttl    card corpus: one sm:Card per fragment (slow churn),
│                        sm:front/back text and/or sm:frontImage/backImage
│                        IRIs, optional sm:frontImageDescription/
│                        backImageDescription (a picture's alt text),
│                        sm:frontNote/backNote under each
│                        side and sm:frontLabel/backLabel above it,
│                        dcterms:subject (what it is about), the
│                        release it was taken from (sm:fromRelease,
│                        outside the card format), each
│                        with sm:formatVersion; a retired card
│                        (owl:deprecated true) is kept but not studied;
│                        a card names its wrong options
│                        (sm:distractor, and schema:suggestedAnswer),
│                        sm:Distractor subjects beside it; a retired
│                        one (owl:deprecated true) is kept but never
│                        offered; the document itself (<>)
│                        dcterms:isPartOf the deck's entry
├── reviews/<deckId>.ttl  SM-2 state: one sm:ReviewState per card and
│                        direction (fast churn) — #<cardId> front→back,
│                        #<cardId>@back-to-front the other way — naming
│                        its card (sm:reviewOf), its direction
│                        (sm:reviewDirection) and sm:scheduler sm:sm2;
│                        optional sm:previous* snapshot = state before
│                        the day's first review (restored by "reset the
│                        day"); sm:formatVersion 2. Beside it, once FSRS-6
│                        has scheduled the prompt, its FSRS-6 state:
│                        sm:scheduler sm:fsrs6, #<cardId>@fsrs6 or
│                        #<cardId>@back-to-front@fsrs6, stability,
│                        difficulty, due day, its own snapshot;
│                        sm:formatVersion 1; the document itself (<>)
│                        dcterms:isPartOf the deck's entry
├── history/<YYYY-MM>.ttl  the answer log (below): one sm:Answer per grade
│                        given in study or a course that month,
│                        appended, never edited; sm:formatVersion 1
├── drafts/<name>/v<N>/   a draft of a release, linked from the catalog
│                        (sm:releaseDraft): release.ttl, its root (the
│                        draft deck, sm:formatVersion 1), agents, sources
│                        and how it was made; chapter-<id>.ttl per
│                        chapter; cards.ttl, the cards no chapter asks
│                        ([below](#drafts-and-releases))
├── releases/<name>/v<N>.ttl  a release published from a draft, linked
│                        from the catalog (sm:publishedRelease): one
│                        document, readable by everyone, never written
│                        again (the user may publish elsewhere instead)
└── digest.ttl      derived data (below): a sm:DocumentReceipt per document
                         (#receipt-<path>), a sm:DeckSchedule per deck
                         (#schedule-<path>) and a sm:MonthSummary per past
                         month of the answer log (#month-<path>), each
                         stamped with the versions it was learned from;
                         a path past 256 characters is named by its
                         hash instead, #<kind>~sha256-<hash>;
                         sm:formatVersion 1 (a receipt or a month
                         summary), 2 (a schedule)

A deck's documents are found through its catalog entry (sm:cardsDocument, sm:reviewsDocument), never by name: an earlier version's library upgrade moved them to decks/<deckId>-<uuid>.ttl and reviews/<deckId>-<uuid>.ttl. Today's upgrade writes them where they are (migrations).

Where an instance's documents are

A catalog, a type index and every link in them are untrusted data (markdown.md). An address they name is used only where Solid Memo keeps such documents, or, for a deck's documents, only as they allow (below). The address and the folder are first taken as a request sends them (new URL(…).href, canonicalUrlOf), which resolves a dot segment (.., %2e%2e in any case) and spells the host and any character outside ASCII one way. Then the address is checked to be in the folder (isDocumentIn in instanceLayout.ts; the graph does the same). An instance written otherwise, https://Pod.example/kortlekar-å/, keeps its decks, and a link that climbs out of it doesn't lead there.

After the folder, an address may hold nothing a server might read as a step out of it, though a request leaves it as it is:

  • a query or a fragment;
  • a ;;
  • an encoded slash, backslash or percent sign (%2F, %5C, %25);
  • a NUL, an overlong UTF-8 byte (%C0, %C1) or a %u escape;
  • a segment that begins with a dot, or an empty one (//, which a client may merge into one slash).

No document Solid Memo names has any.

  • A deck's documents are read wherever its entry names them. Their folders and names are free: a user or a tool may rename decks/ and reviews/, move the documents elsewhere in the pod, or lay the pod out flat, with the instance at the pod's root. A moved document's subjects are to name its new address. The app writes them as absolute IRIs, so a copy byte for byte still names the old one. Its cards and review states are then another document's subjects, which are never read as the deck's. Relative IRIs (<#card-1>) move with the document. A deck can be used when its entry is a subject of the instance's catalog.ttl and each document is at an address a deck's may be (isDeckInPlace, isDeckDocumentAddress in deckAddress.ts). That's plain http(s), with nothing a server might read as a step elsewhere (as above). It isn't a folder, an access control or metadata resource (.acl, .acr, .meta), or one of the instance's own documents (its meta, preferences, palettes, catalog and digest, history/, drafts/, releases/). It's in a guest's pod exactly when the catalog is: only a guest's own instance names that pod, which is this browser's (guest-mode.md). New decks are made in decks/ and reviews/. One outside the user's own pod (their storages and the instances they registered) is read as no one, and nothing is written to or deleted there, whatever it says (writeOutsidePod, boundaries.md). Removing its deck, or deleting its instance, keeps it. One in the instance's storage that says it's the deck's is named as kept. In an instance from someone else's pod, only documents in the instance's folder are the user's: a deck whose documents lie elsewhere in that pod can be read only if they're public, and can't be studied.

  • A deck's document is written to, or deleted, only when it says it is the deck's: the document states <> dcterms:isPartOf <catalog.ttl#deck-X>, naming this deck's entry (ownsDocument; below). Anyone who may append to a document can state that, so the statement alone doesn't make a document safe to change. It counts only for a document in the instance's folder or in the storage the instance is in. When one of the user's storages holds the document or the instance, that decides it: both must be in the same one. Those are the storages their profile names (pim:storage), or else the storage's root the server shows above their WebID (discovery chain). Otherwise both must be under the same storage's root that the server shows (typed pim:Storage, or named by a Linked Web Storage server), with no other root between it and either of them. A folder that holds both isn't enough: a server may hold many users' pods under one root it doesn't type. Anywhere else it's unclaimed, whatever it says, and nothing is written to or deleted there for the deck. A deck whose documents are in another storage, even one of the user's own, is read-only until they're moved into the instance's storage. When the profile can't be read, or the pod doesn't answer for a folder on the way, a write fails and can be retried; the data check and a removal take the document for unclaimed that time. The storage rule doesn't tell who made the instance. So what keeps the rest of the document safe is what a removal takes out of it: only subjects that say nothing but what Solid Memo writes of a card, distractor or review state (below). A draft made from a release holds what others wrote, so it never keeps a statement that one of its documents is dcterms:isPartOf anything (draftEntries). A release (<> a sm:Deck) is never a deck's document, whatever it says, nor is a draft's own document in its folder: its release document, cards.ttl or a chapter's. It's unclaimed, and claiming leaves it as it is (isDeckItself in ownership.ts and isDraftDocument in deckPlace.ts).

  • An older document that doesn't say so (from an earlier version, a repair or a copy) is the deck's in the instance's own folder. That folder isn't the instance's own when it's the root of a pod or a storage, or a folder above one. Such a root is one of the user's storages (as above), which a server may leave untyped, or a root the server shows (typed pim:Storage, or named by a Linked Web Storage server). In the instance's own folder the next write states it. When the profile can't be read, a write fails and can be retried. The data check and a removal then read the document, and take it for unclaimed unless it says it's the deck's. One that names any other catalog's entry (such as a nested instance's) isn't the deck's: the app never adds a second owner on its own, and refuses the write (deckDocumentUnclaimed). The data check doesn't read a document in the instance's own folder to list it as unclaimed; it leaves one out once it has read it and found it isn't the deck's, and a repair makes the same decision. The folder is asked once a session; when the pod doesn't answer (an error or a refusal, cannotCheck), the write fails and can be retried, and the folder is asked again; the document isn't taken for unclaimed. A refusal before anything is sent, deckDocumentUnclaimed among them, leaves a library upgrade saying nothing was changed. A document not yet made is made only in the instance's folder.

    Anywhere else the app never states it on its own: the document is unclaimed. The deck is read and studied, but each answer, edit or removal that would touch the document is refused with deckDocumentUnclaimed before anything is sent, and removing the deck removes only its entry. The instance check names such a deck with its documents' addresses, in the data check and the Studio's Health screen, with "These are this deck's documents". Once the user confirms, each document is made to say it's the deck's: one write made only while it's as read (If-Match), or only where there's none (claimDeckDocuments; createDeckDocumentGuard in deckPlace.ts). The claim is only for documents in the instance's folder, or in one of the user's storages, as found at that moment, that holds the instance too (isInInstancePod). An instance attached from someone else's pod may name a document of the user's own, and writes to that document go out as the user. Any other document is refused (claimOutsidePod), and the deck is shown without the button. A document in the instance's storage that already says it's the deck's stays the deck's. Removing a deck, or deleting its instance, takes out a document's cards, distractors and review states only when every deck it names is leaving; otherwise only the leaving deck's dcterms:isPartOf goes (deckDocumentSubjects in ownership.ts). A subject goes only when it's a card, distractor or review state of Solid Memo's (not one of another scheduler) and says nothing else. Each class it states is sm:Card, sm:Distractor, sm:ReviewState or a distractor's schema:Answer. Each property is rdf:type, one of the card, distractor, review state or FSRS review state shapes at any version, sm:formatVersion, sm:fromRelease or schema:suggestedAnswer. A subject with any other class or property, Solid Memo's own too, such as preferences that also say they're a card, stays whole. Nothing they link to goes with them, and the document's own subject goes only when all it says is that it's the deck's. A failed read (refused, a server error, no answer, a download cut off) of a deck's document in the instance's folder stops the removal, or the instance's deletion, before the catalog is written. The entry stays, the error is shown, and trying again finishes it, a document already gone (404, 410) counting as removed. A deck's removal makes the new catalog before it deletes any document, so an entry, a distribution, an agent only the removed decks name or the catalog node a newer version wrote refuses it (writtenByNewerApp) with every document still there. A document outside the instance's folder may be anyone's and may never answer, so a failed read doesn't hold the deck back: it's kept whole, the result names it (keptDocuments), and the entry goes. The same holds for one the pod serves that can't be read as RDF.

  • Any other deck is left alone. It isn't listed (toDecks in deckMapper.ts), so nothing reads, writes or deletes through it, whatever the invalid data policy. The instance check reports its entry as not conforming (DeckPlace). Removing it there, like any problem with no repair, removes the entry from the catalog and no document it names. A deck handed to the adapters from anywhere else is held to the same rule: a write through it is deckGone, with nothing written, and removing it removes only its entry (removeDecks in solidDeckRepository.ts).

  • A draft the catalog links (sm:releaseDraft) is one only at <instance>drafts/<name>/v<N>/release.ttl, in the instance's drafts/ as a request sends it, with no dot segment, and with N a safe integer, so the address names the same draft again (draftPlaceOf). A name that's a dot segment is no draft's.

  • A release the catalog links (sm:publishedRelease) is listed only at an http(s) address named as a release is, …/<name>/v<N>.ttl, written as a request sends it, like the folder it's published in (studio.md). That address has no empty segment (//) and no user info (isPublishedReleaseUrl). It's made public again only when the catalog lists it, its document is a release, and it's in the instance or in a storage of the user's that holds the instance. An instance attached from another's pod may list the user's own. Its next version, written into the instance, is made from it read as the user only by the same place rule, and from it read as no one otherwise. So is a draft made from a deck, from the deck's cards, and so are the deck list's counts and the format update's plan, from a deck's cards and reviews documents. The digest keeps nothing of a deck unless both are the instance's.

Decks and cards

Reading a whole deck is one GET (the N+1 problem: Solid servers have no batch requests or SPARQL), and a study session never rewrites card content.

graph LR
    accTitle: An instance's documents
    accDescr: A deck in the catalog links its creator, its distribution, its cards document and its reviews document, and each review state points to its card.
    C["catalog.ttl#deck-X<br/>a sm:Deck, dcat:Dataset<br/>dcterms:title, dcterms:description<br/>sm:formatVersion<br/>sm:studyDirection<br/>sm:cardsDocument<br/>sm:reviewsDocument"]
    A["catalog.ttl#agent-…<br/>a foaf:Agent<br/>foaf:name, foaf:mbox"]
    X["catalog.ttl#deck-X-cards<br/>a dcat:Distribution<br/>dcat:accessURL"]
    C -->|dcterms:creator| A
    C -->|dcat:distribution| X
    D["decks/deck-X.ttl#card-N<br/>a sm:Card<br/>sm:front / sm:back<br/>sm:frontImage / sm:backImage<br/>sm:formatVersion<br/>owl:deprecated (retired)"]
    R["reviews/deck-X.ttl#card-N<br/>reviews/deck-X.ttl#card-N@back-to-front<br/>a sm:ReviewState<br/>SM-2 fields<br/>sm:reviewDirection, sm:scheduler"]
    C -->|sm:cardsDocument| D
    C -->|sm:reviewsDocument| R
    D -.->|the document: dcterms:isPartOf| C
    R -->|sm:reviewOf, else the same fragment id| D
Loading
  • The catalog holds one subject per deck with its title and links to the two documents, so the deck list renders from one fetch. A deck's title and description are language-tagged text, one value per language, in any language the user states since deck format 5 (format 4 required English; i18n.md). Since deck format 3 a deck is a DCAT dataset (dcat:Dataset, vocab.md, validation.md):

    • It always has a description (dcterms:description): what it covers and where its content came from. It's shown on the deck page, its URLs as links. A deck without one gets "Flashcards: <title>."@en and "Kortlek: <title>."@sv (app-written text for any title). A title too long for the description to fit the bound on a term is cut short in it, with an ellipsis after it (migrations.md).
    • It may name its authors (dcterms:creator), each a foaf:Agent node #agent-<slug> beside the deck, with foaf:name and a mailto: foaf:mbox, shown as Name <email>. Only a bare address counts as the email: one with ,, ;, ?, #, % or & in it leaves the whole author a name, shown without a link. A subject that also has another class a shape describes, as a deck itself does, names no author: the app shows the author's address. The slug is the author folded to ASCII, unnamed when nothing is left of it. An author the folding loses letters or digits of, such as 김민수 or "Kim 민수", or that has none to lose, such as "—", gets six hex digits of a hash of the whole author after it (#agent-unnamed-5a5e6e, #agent-kim-ad54ba). Two such authors stay two agents. Every deck of the catalog names its authors' nodes, so a node that already holds another name or email is never written over. An author whose slug another author holds, such as Jane Doe (jane example org) beside Jane Doe <jane@example.org>, gets the hash after the slug instead (#agent-jane-doe-jane-example-org-<hash>). When that node is taken too, a count follows the hash: the lowest whose node is free or holds that author. The counted nodes of one such name are looked at once for all the authors that share it, so the time grows with the authors and the nodes, not their product. A node's URL, joined from the document and the name, can be longer than any term, so the app keys it by its pieces (TextMap in pathKeys.ts) and refuses to write a deck or draft that would hold one. An agent is read by the IRI the deck names (one written under an older rule is replaced on the deck's next save). A deck save, rename, import, format upgrade or removal takes out the agent nodes no deck names any longer, but only Solid Memo's own. Another app's subject at an #agent-… fragment stays, and of Solid Memo's node only its agent statements go. A node that lost Solid Memo's format stamp counts as another app's, so it stays too.
    • It may name a license (dcterms:license, a URL), topics (dcat:theme, concepts of the topics scheme) and keywords (dcat:keyword), language-tagged since deck format 6, several per language; untagged ones saved before are kept, their language unknown.
    • No shape bounds how many authors, topics, keywords or languages of its title and description an entry holds, or how long they are, and the catalog is read and written whole. So the app keeps at most MAX_DECK_METADATA (100) of each: authors, topics, languages of the title, of the description and of the keywords, and keywords in one language. It keeps at most MAX_DECK_KEYWORDS (1,000) keywords in all, and at most MAX_DECK_METADATA_CHARACTERS (65,536) characters of them all together, the first language of the title and of the description always, as the shape requires both (withBoundedMetadata, deck.ts). All are far more than any deck in decks/ has. Past the bound it keeps the first values that fit: the title's languages, the description's, the authors, topics and keywords, in that order and in their stored order, and a keywords' language only with a keyword. A release's content, a deck file's import, a new entry, an upgrade and a read keep them so. Every write of an entry leaves out what it held past the bound, so an entry saved before holds it until the deck is next saved.
    • Its cards document is its dcat:distribution (#deck-X-cards, with dcat:accessURL).
    • A deck copied from the deck library, or from a release added from a link, names the release it came from with prov:wasDerivedFrom (dcterms:source before format 3), wherever that release is; it's read, never written. A link the URL parser doesn't take reads as none, so the deck is a copy of no release, and the next write of that deck's entry leaves the link out.

    Agents no deck names any more go with the deck that named them. The Studio edits the authors and the license (setDeckProvenance, deckProvenance.ts). Two authors that would share an agent node are refused, and a license is one of KNOWN_LICENSES (license.ts) or the one the deck has.

  • Card sides: each side is text (sm:front / sm:back, a literal), a picture (sm:frontImage / sm:backImage, always an IRI; a string there is ignored) or both; a side with neither makes the subject not a card. A side's text is language-tagged, one value per language (zxx for codes, numbers and symbols), or, as saved before card format 5, one untagged literal of unknown language, never both; untagged text is kept only while untouched. A note under a side (sm:frontNote / sm:backNote) and the label above it (sm:frontLabel / sm:backLabel, the front's since card format 6) are language-tagged text in any language.

    Pictures are shown only when their URL is http(s). A picture may have a language-tagged description (sm:frontImageDescription / sm:backImageDescription), read to whoever can't see it, in its place, while its side is asked, so it never gives the answer away. Without one it's named by its side ("Picture on the front of the card").

    A card may say how its texts are written, sm:textFormat (sm:markdown or sm:plainText, vocab.md), for the sides, the notes, the labels and the card's distractors, never the pictures' descriptions; without it the text is plain. A card copied from a library release keeps what it's about, dcterms:subject (card format 7, deck-library.md), which the app neither shows nor edits. Every edit and copy keeps both, an import or a course question joining the deck included. An edit trims plain text; text in any other format loses only the blank lines before it and the white space after it, so the spaces that start a Markdown code block survive.

    Wherever a side is shown whole (study, a library preview, a card's page, a library card), a tap, or Enter or Space on the button over it, enlarges its picture to the viewport's width or height, keeping its shape. Enlarged, a pinch zooms the picture, not the page, up to four times; a double tap zooms in on the spot tapped and another zooms back out; a drag moves it while zoomed in. Pinched out past its fit, it springs back. A single tap, Escape, throwing it up or down, the focus moving on or a scroll puts it back (ZoomableImage). In study, Space on a picture's button doesn't reveal the answer; a grade's key still answers.

  • Direction: a deck's sm:studyDirection is a concept of sm:StudyDirections: sm:frontToBack, sm:backToFront or sm:bidirectional (every card asked both ways). Formats 1 and 2 used the string sm:direction, absent meaning front→back. It's changed in the Browser; a library deck brings its own.

  • Study pace: a deck may set its own daily limits, sm:deckNewCardsPerDay and sm:deckMaxReviewsPerDay, in place of the instance's sm:newCardsPerDay and sm:maxReviewsPerDay; a limit it doesn't set follows the preferences.

  • Card language: a deck may name the language its card text is shown in first, sm:deckCardLanguage, one lower-case language tag. Its fronts, backs, notes, labels, picture descriptions and wrong options then rank that language ahead of the app's; a card without text in it shows as usual (i18n.md). On a course's deck it ranks the course's text too, on the course's own screens: the course's title and description, its chapters' titles and descriptions and its steps' theory. The keywords, and a plain deck's title and description, don't follow it.

    Like sm:position and sm:completedChapter it belongs to no shape (DeckV6 is unchanged). Every other write of the deck keeps it as the entry has it (withDeck), so a deck read before it changed can't undo it. Only setCardLanguage sets or removes it, on the entry as it is then (If-Match), as completeChapter adds a chapter. A new entry (an import, a guest's deck moved) is written with the deck's, and a reader drops a value that names no language. It's chosen from the languages its cards state, and a release drafted from the deck leaves it behind.

    The study pace and the card language are set on the deck's own Preferences page (#/deck-preferences, from the deck's page). A library release never sets them, and a library upgrade keeps the copy's.

  • Picture hosts: a deck copied from a release outside the library's index shows a card's picture only from a host the learner chose for it (privacy.md). Each is one sm:deckPictureHost, as a URL writes it with any port that isn't the default. Like sm:deckCardLanguage it belongs to no shape, every other write of the deck keeps it as the entry has it, and only setPictureHost adds or removes one, on the entry as it is then (If-Match). A new entry is written with the deck's, a reader drops a value that's no host, a library upgrade keeps them, and a release drafted from the deck leaves them behind. A release never sets them: reading one doesn't read the term. In a catalog outside the learner's own pod the term isn't believed, as that pod's owner writes it, and nothing is written of a choice there.

  • Format versions: every subject the app writes carries sm:formatVersion, the version of its class's shape it conforms to. The instance is at 1, decks at 3 (DCAT), cards at 2 (pictures), review states at 2, preferences at 6 (the palette and the text size) and deck schedules at 2 (the scheduler). The catalog, agent and distribution nodes, and a palette of the user's own and its color sets, are at 1. Readers treat a missing version as 1, read older versions as they are, and pass a newer one through unchanged. Bringing a pod up to date is the user's call (migrations.md). A developer can check an instance against the shapes in the browser.

  • Cards are hash-fragment subjects (#card-<uuid>, or the library's own ids such as #sweden for imported decks) inside one document per deck. Fragment ids are generated once at creation and never re-derived. A card's id is its fragment, so only the document's own subjects are its cards (ownSubjectsOf in records.ts). Their address is spelled exactly as the deck's entry spells it, where the app writes them, or as the document is fetched, as a relative IRI such as <#card-1> is read. A fragment at both is the one the entry spells. A subject at another document, or at another spelling of the same address (another host case, the default port, a dot segment), is never read as a card, though it shares a card's fragment. Card edits and removals never reach it.

  • Review state lives in a separate document per deck, one subject per card and direction: #<cardId> for front→back (as was every state written before directions existed), and #<cardId>@back-to-front for the other way. Since vocabulary 1.16 every state the app writes says what it's of: sm:reviewOf names the card (<cards document>#<cardId>), sm:reviewDirection the direction (sm:frontToBack or sm:backToFront) and sm:scheduler sm:sm2 the algorithm of its fields. A reader joins a state to its card in reviewStateMapper.ts and reviewRecord.ts:

    • What the state says wins. The card is the one sm:reviewOf names and the direction the one sm:reviewDirection names; what the state leaves out comes from the fragment rule above (no @back-to-front suffix: front→back). A state another app named #state-7f3a is read when it names its card, and #card-1 naming card 2 is a state of card 2.
    • A link into a cards document the deck had names its card too (an earlier library upgrade moved the cards). sm:reviewOf into any document beside the cards named <deckId>.ttl or <deckId>-<…>.ttl is read by its fragment. The state's next write names the current cards document.
    • What isn't read: a subject that isn't the reviews document's own, by the cards' rule above, whatever it says, which removing a card leaves too. A state whose sm:reviewOf names a subject outside the deck's cards documents (another deck's card, or the document's own subject). Nor one whose direction is neither way (say sm:bidirectional), or of another scheduler: any value of sm:scheduler but the sm:sm2 and sm:fsrs6 IRIs, a literal too. Absent means SM-2. Another scheduler's state is never read, written over or removed, the check only warns about it, and the app schedules the card beside it.
    • An FSRS-6 state is the app's own (vocabulary 1.21): an sm:ReviewState naming sm:scheduler sm:fsrs6 and nothing else, beside the SM-2 state of the same prompt. The app keeps that one up to date on every review, whichever scheduler sets the due days (srs.md). It's read by its sm:reviewOf and sm:reviewDirection alone, which its shape requires, and written at #<cardId>@fsrs6 (front→back) or #<cardId>@back-to-front@fsrs6, from which the fragment rule reads no card. One per card and direction counts, by SM-2's rule (the one at the subject the app names for it first), and only while fresh (the SM-2 state has the same sm:lastReviewedAt). A stale one (an older app graded SM-2 alone, the day was reset, the card forgotten) and an orphan (no SM-2 state beside it) set no due day; the next review under FSRS-6 replaces it, estimated from the SM-2 state. A change to the SM-2 state that keeps its last review goes unseen. An older app's Set due date in the Studio moves the SM-2 due day alone, and under FSRS-6 the FSRS-6 due day still counts until the card's next review.
    • One state per card and direction. Where several are of the same, the one at the subject the fragment rule names counts, else the first by subject IRI (code-unit order); the others stay, unread.
    • Writing a state goes onto the subject read for it, so a review of another app's #state-7f3a edits it in place. A state not yet in the document goes to the subject the fragment rule names, unless that subject is another's (another card's state, another scheduler's, any other app's subject) or is too long. A card id that fills the card's address, as a deck file or release can carry, makes the named subject, with @back-to-front and @fsrs6 after it, longer than a term may be (write discipline). Then the state goes to a new #review-<uuid> that names its card, and is read and written there from then on. A subject the fragment rule names for the same card and direction that can't be read (half a snapshot, say) is written over. An FSRS-6 state goes the same way, to the subject named for it. A grade under FSRS-6 writes both states in the one PATCH it makes under SM-2; under SM-2 the FSRS-6 state is left as it is, and goes stale. foreignData.integration.test.ts reviews, on real servers, a state another app named its own way, beside another scheduler's state.
    • Resetting the day removes only the state read for each card and direction it undoes; a second state of the same stays, and is read from then on. FSRS-6's states of the day go back in the same save: restored to their snapshot, or removed when introduced that day or without one (srs.md).

    Card edits and review updates never touch each other's documents.

  • Cards and reviews documents are created lazily on first write. Deck removal deletes both documents and the catalog subject. Card removal removes every sm:ReviewState of the card, both ways and read or not (SM-2's by sm:reviewOf or the fragment rule, FSRS-6's by their links), and no other subject (another scheduler's state stays). The Studio's edits do the same (studio.md), as does a card moved away or forgotten (applyReviewChanges with every).

  • The cards and reviews documents say whose they are. Every write of a deck's cards or reviews document by the deck's own operations adds <> dcterms:isPartOf <catalog.ttl#deck-X> once, on the document's own subject, never on a card or a review state. Those operations are:

    • import;
    • adding, editing or removing a card, and stating its languages;
    • an answer, and a day reset;
    • a course's question joining the deck;
    • the format update's rewrite of outdated cards and states;
    • a library upgrade's write of the cards and states;
    • a guest's deck added to an instance.

    It tells Solid Memo it may change the document (above). An import or a library upgrade reads and writes the cards and states as without it, and a release is never written. A repair from the data check and a copy of the instance (a guest's study moved into a new instance) leave the document as it was. One untouched since vocabulary 1.16 (a reviews document, since this version) doesn't say it yet. Another dcterms:isPartOf there stays (another app may point two decks at one document). One naming another deck's entry is added to only when the user claims the document for this deck too. The subject has no class, so no shape checks it. When it says no more than that, it's Solid Memo's (isDeckBackLink in ownership.ts), and the data check doesn't list it as a stray.

An instance's URL is permanent, and so is every document's and subject's in it: the format update and the library upgrade write the documents where they are, and change no registration: the format update writes nothing outside the instance. Another app may keep a link to the instance, a deck, a card or a review state.

The catalog

catalog.ttl#catalog is a dcat:Catalog (shape CatalogV1) of the instance's decks. It has a dcterms:title (the instance's name), a dcterms:description and a dcterms:publisher: the pod owner's WebID, described in the same document as a foaf:Agent with their profile's foaf:name. Its dcat:themeTaxonomy names the topics scheme and the EU data themes, and its dcat:dataset each deck. It may state a license (dcterms:license), which the document then types a dcterms:LicenseDocument, as DCAT-AP asks; a license it no longer states loses that type.

Saving a deck adds only that deck's link, and removing a deck removes only its own. A dataset another app listed in the catalog stays listed through every deck save and every write of the whole catalog. The one link a whole write drops is one to a subject of the catalog's own document that's no dcat:Dataset, left by a deck removed some other way (it would fail DCAT-AP's class check). A member another app described in the document keeps its link whatever its class; the check only warns about it (validation.md). A dataset in another document isn't held to its class (validation.md), and an instance listing one stays valid on real servers (foreignData.integration.test.ts).

A catalog is data anyone may have written, so the app reads at most MAX_CATALOG_LINKS (1,000) decks of it, in the deck list and its arrangement, the statistics and the format update as in the Studio (catalogLinks.ts). Past that, it reads none of them and says why (catalogTooManyLinks). So no deck is added past it. A new deck, a copy from a link or a course, or a deck file is refused before anything is written once the catalog has that many (catalogFull). A guest's decks that would take it past them are refused too (guestMergeTooManyDecks). The same limit holds for its links to drafts and releases (Drafts and releases). The deck list works out the study counts of three decks at a time (getStudyCounts in study.ts), each reading the deck's two documents, so a long list never reads all of them at once.

The catalog is written when an instance is created, and by the format update for an instance made before there were catalogs; it has no registration of its own (Discovery chain). A catalog that doesn't fit its shape is invalid data, which no write replaces with another. The whole document conforms to DCAT-AP, a course's deck typed schema:Course too (Courses), and a test holds what the app writes to it.

The instance's name is in the meta document's dcterms:title, the catalog's dcterms:title, and the dcterms:title of its registrations in each type index. Its sm:Instance one names it in the instance list, beside any an earlier version wrote for its data. Renaming it in the Studio (renameInstance, studio.md) writes them all, each document read and written again on a 412. A catalog description the old name gave (defaultCatalogDescription) follows the new name; one the user wrote stays. A name too long for that description to fit the bound on a term is cut short in it, with an ellipsis after it.

A deck's description, topics and keywords are edited in its Browser ("Describe deck") and on its about screen in the Studio, the keywords as one comma-separated list per language the user states. The description is required, as DCAT-AP asks. Only the keyword languages the user states in an edit are checked and stored in their canonical form ("iw" → "he"). A tag the deck already has is kept as stored, even one another app wrote that the app wouldn't accept from the user.

Deck groups

The user arranges the deck list into named groups that can nest. A group is a subject of catalog.ttl beside the decks, a sm:DeckGroup and a dcat:Catalog (shape DeckGroupV1), never a dcat:Dataset, listing sub-catalogs with dcat:catalog and datasets with dcat:dataset, as DCAT-AP allows. The order is Solid Memo's own sm:position (DCAT's dcat:prev/next are series versions, and the library uses them as such).

<#catalog> a dcat:Catalog ; …
    dcat:dataset <#deck-a>, <#deck-b>, <#deck-c> ;   # still every deck
    dcat:catalog <#group-x1> .                       # the top-level groups
<#group-x1> a sm:DeckGroup, dcat:Catalog ;
    sm:formatVersion 1 ;
    dcterms:title "Languages"@en ;                   # one name, in the UI's language
    dcterms:description "Deck group: Languages."@en, "Kortleksgrupp: Languages."@sv ;   # generated
    dcterms:publisher <https://alice.example/profile/card#me> ;   # the catalog's
    dcat:dataset <#deck-a>, <#deck-b> ;
    dcat:catalog <#group-y2> ;
    sm:position 0 .
<#deck-a> sm:position 0 .
  • The catalog still lists every deck with dcat:dataset; a group lists only its own members, and the catalog's dcat:catalog the top-level groups. An edit writes only the links to the decks and groups the arrangement places; a member link to a dataset or catalog in another document, or to one the app can't read, stays.
  • A deck or group is in one parent: the catalog (top level) or one group; a deck no group lists is at the top level.
  • Positions count within one parent, decks and groups in one sequence, 0 first. Members sort by position, those without one last, in document order. The first arrangement of a level writes positions 0…n−1 for every member at that level; new and imported decks get none.
  • An empty group stays until the user removes it; removing a group moves its members, in order, into its place in its parent.
  • A group's description is generated: "Deck group: <name>."@en and "Kortleksgrupp: <name>."@sv, written anew whenever an edit writes the group, unless it holds text the user wrote. A name too long for the description to fit the bound on a term is cut short in it, with an ellipsis after it, as in a deck's. The whole text an earlier version wrote still counts as the generated one.
  • sm:position on a deck and the catalog's dcat:catalog belong to no shape (DeckV6 and CatalogV1 are unchanged), so writing a deck or the catalog keeps them.

What isn't one valid tree is read as one, not refused. A link to nothing, from a group to itself, or of the wrong kind (a dcat:dataset link to a group, a dcat:catalog link to a deck) is ignored. A subject the app reads as a deck is a deck only, even when it's also typed as a group: it's never a group too, and its own links to members are ignored. A node several parents list goes to the group with the lowest URL, except a group the catalog's dcat:catalog lists, which stays at the top level. A cycle is broken by moving its lowest-URL group to the top level. A group nested deeper than 16 groups (MAX_GROUP_DEPTH) is read at the top level, with the groups it holds counting their depth from there. The editor doesn't stop a move that nests a group deeper, so the next read shows that group at the top level. A negative position counts as none, and so does one larger than the app holds exactly (2^53 − 1): the node sorts last, and a group written again is written without it, or renumbered when its level is reordered. On a tie of positions, decks come before groups, each kind in document order. A group in a format newer than the app's makes the arrangement read-only. So does, under the "Set invalid data aside" policy (sm:blockSubject, the default), a catalog or group that doesn't conform, or that check still running (validation.md). A group the app can't read is never edited: its members show at the top level, and the catalog's dcat:catalog keeps its link.

Writing an arrangement. The screen sends an edit, not a finished layout (DeckTreeEdit in deckTree.ts). An edit moves a node after a sibling, combines two into a new group, renames or removes a group, or gathers decks at the end of a group (the Studio's bulk move). Keeping a guest's study grafts new groups around decks the tree has at the end of the top level, a no-op once one of its groups is there. The repository (editDeckTree in solidDeckRepository.ts) applies the edit to catalog.ttl as the pod holds it then:

  • read, apply, write once: what changed is written in one PATCH with If-Match (write discipline); an edit that changes nothing sends nothing;
  • on 412 the edit is applied again to the document as it is now, three attempts in all, so another tab's change is kept. A move names its neighbor, not an index, and the screen mints a new group's URL (newDeckGroup), so an edit means the same on the fresh tree, and a retried combine is a no-op. An edit that no longer fits (its group or node gone) fails with deckTreeChanged;
  • a PATCH, never a whole PUT: where the pod has no strong ETag, a PUT would undo what changed since the read;
  • only the groups written and the catalog are checked before the write (checkWrite), so a deck set aside beside the one moved doesn't stop the move;
  • removing a deck removes it from every group's dcat:dataset too, in the same write; its siblings keep their positions, and the next arrangement closes the gap. A group a newer version wrote keeps its link, which reads as no member once the deck is gone.

Several decks at once. The Studio changes several decks in one write of catalog.ttl (studio.md). A move into a group is one gather edit, which leaves a deck already in the group where it is, so a retry changes nothing. A pace or a direction is one save of every entry (saveDecks). Removing decks first removes their cards and review states from their documents, deleting each document that then holds nothing else (one holding another app's data too is kept, keptDocuments), then their entries in one save (removeDecks). Either way the catalog document is rewritten once for all the decks (withDecks, withoutDecks), not once per deck, so a change to many decks takes time that grows with them, not their square. A link of the catalog or of a deck group that is no URL the app can write (another app may have written one) stays as it is, and the rest of the links are changed around it. The same holds when the deck list is rearranged: such a link is no member of the arrangement, and renaming, moving or combining groups keeps it.

Wrong options

Any card may have wrong options, shown beside its back in a multiple-choice question (courses.md). Each is an sm:Distractor subject of the card's document, typed schema:Answer too, with sm:formatVersion 1, its text (sm:distractorText) and, optionally, why it's wrong (sm:distractorNote). The card names each with sm:distractor and, since vocabulary 1.16, schema:suggestedAnswer (below), in step through every write of a card (bulk edits, moves, copies and imports, a course's question joining the deck included). Solid Memo's card editor and the Studio's card inspector edit them (studio.md; the domain is distractors.ts):

  • A new one is written once it has text, as #<card>-d<n>. n is one more than the highest such id of up to 15 digits the card or the release the deck came from has used, or the first free one after it. An id the release published is never used again (a learner's answers may name it, sm:chosenDistractor); one deleted before it was published may be. A card is never saved with two of one id, which would be one subject: a write of such a card, an imported deck file's too, is refused before anything is sent (writeDistractors).
  • Retiring one writes owl:deprecated true on its subject, and restoring it removes that. A retired one stays named by the card, is read marked retired (toDistractor) and kept by every write, and only a question's choices leave it out (choicesOf).
  • Deleting one removes its subject and the card's link to it, in the one write of the card, and only one the deck's release never published; one it did is retired instead.
  • Each change is a write of the card (updateCard): the card and its distractors are written, those it names no more removed unless another card names them (withoutUnnamedDistractors), and triples the app doesn't know kept (withDistractors).
  • A wrong option not in the back's languages is a warning in a pod's deck, never a refusal. It names the first three languages the option lacks, or has that the back lacks, and counts the rest.
  • A card and a distractor never share an id. Both are subjects of the cards document at their ids. A write of a card onto an sm:Distractor subject, or of a distractor onto an sm:Card subject, is refused before anything is sent (idTakenInDeck), and the deck is left as it was.
  • A distractor belongs to one card. A write that leaves a distractor it writes named (sm:distractor) by two cards is refused the same way (assertDistractorsOwnedOnce), so an upgrade never gives a distractor a card keeps to another card. Removing a card, or a distractor it no longer names, never removes one another card still names, nor any subject that isn't a distractor. A card's sm:distractor link to another card, or to a subject the app can't read as a distractor, leaves the card in its next write, and the subject it named stays. A link to an IRI that is no URL names no subject the app reads (getThing finds nothing there), so the card and the rest of its document are still read.
  • A deck an earlier version left mixed up may have a subject typed both sm:Card and sm:Distractor, or a distractor two cards name. A write of such a card is refused (idTakenInDeck) rather than made onto the other's subject. While another card names the subject as its distractor, removing the card that took it over, by hand or in an upgrade, removes only the card statements: the sm:Card type and the card properties (withoutCardSubject). The other card keeps its distractor and is editable again. A card may also name two distractors of one id, subjects of two documents, as only a document written by hand can. It still reads, and the document's other cards can be edited. A write of that card is refused (distractorIdRepeated), and so is an upgrade of its document to this app's format, which stays as it is until the user deletes one of the two (deleteDistractor, by position) and saves the card.

Courses

A course is a library release with an outline of chapters and steps. Its state uses the documents above and no new type-index entries:

  • The outline stays in the release. Chapters and steps are never copied: the app reads them from the release the deck's prov:wasDerivedFrom names.
  • The deck holds only the cards answered. Starting a course writes an empty deck. A question answered for the first time writes its card, its sm:Distractor subjects and its first review state, under the release's fragment ids (#q-why-solid-1a, #q-why-solid-1a-d1), and its sm:textFormat when the release states one. The app reads only sm:distractor; a write of the card adds or removes only the schema:suggestedAnswers that are its own distractors, so another app's stay. schema:suggestedAnswer belongs to no shape, and only the copy in the pod states it, never a library release. Removing a card removes the distractors it names.
  • The entry says it is a course's deck. Starting a course types its catalog entry schema:Course too, beside sm:Deck and dcat:Dataset, as its release is typed (Deck.course). The deck shape asks only that the entry be a dcat:Dataset and isn't closed, so the deck format didn't move and every write of the entry keeps the type. A deck added from a guest's study and a deck file carry it, a file without the progress too. A copy made before the type lacks it; the library's index, or the copy's own release, tells it a course.
  • Completed chapters are on the catalog entry: one sm:completedChapter <release#ch-…> per chapter whose final review was passed, kept by every write of the entry. It's added with an If-Match PATCH, three attempts in all, as a deck group edit is. A deck added from a guest's study (addDeck) gets the guest's completed chapters with its new entry, and the Studio marks a chapter not done, or restarts the course, the same way (setCompletedChapters), a write that passes the shape check. No shape bounds the values, so the app keeps at most MAX_COMPLETED_CHAPTERS (1,000) of an entry, each URL once, more than any course has chapters. Past that bound, it first leaves out the values of no document of the course: the deck's release, and on an import its cards' releases too. Then it leaves out the oldest. So values of other documents never push a chapter the learner completed out. A read, a deck file's import and a new entry keep them so. An edit writes the values it keeps and those it adds in one go, by the same rule, a chapter it adds counted as the course's, and drops the values past the bound from the entry.
  • Answers go to the answer log, with sm:answerMode.
  • Everything else is derived: a step is done when each card it's checked by has a review state, and a chapter opens when the one before it is completed.
# catalog.ttl
<#deck-x> a solid-memo:Deck , dcat:Dataset ; …
    prov:wasDerivedFrom <https://solid-memo.com/decks/solid-fundamentals/v1.ttl> ;
    solid-memo:completedChapter <https://solid-memo.com/decks/solid-fundamentals/v1.ttl#ch-why-solid> .

Drafts and releases

Vocabulary 1.18 and its shapes let a creator write a release in their own pod, as a draft, before publishing it (vocab.md, studio.md):

  • A draft is a container of the instance, drafts/<name>/v<N>/ (the version it drafts), holding

    • release.ttl: the release's root, the draft deck, which is the document itself (<>) as a release is its document. It holds the deck's agents, its distribution, its sources, how it was made (its prov:Activity subjects, license documents) and the series it describes;
    • chapter-<id>.ttl for each chapter: the chapter, its steps, the cards they and the chapter ask, and those cards' distractors;
    • cards.ttl: the cards no chapter asks (a plain deck's, or questions not yet placed) and their distractors.

    A subject keeps its fragment id in whichever document it's in, and moves with its place (a question moved to another chapter goes to that chapter's document); what names it names it where it is. A subject a document names otherwise isn't read as the draft's, and publishing the draft refuses it (inPlaceIn in releaseDraftMapper.ts). The names that count are those of the draft's documents: release.ttl, cards.ttl and chapter-<id>.ttl. Named otherwise is a fragment of another of them, one of them other than the release document, or the release document as a subject in the cards document or a chapter's. A fragment of a document's own address counts as named where it is, whichever document the draft gives that subject: what two documents state of one subject is read as one. A chapter's document left with nothing in it is deleted. Anything else in the container (isDraftDocumentName in draftLayout.ts) is another app's, and left alone. Every id of a draft is letters, digits, ., _ and -, starting with a letter or digit (DRAFT_ID), so a chapter's document is always in the draft's container. A draft whose documents name a subject otherwise is neither opened nor written (draftIdUnsupported). Nor is one whose documents state a subject the draft reads by its shape otherwise than its record writes it (draftHiddenValue), such as a second text in a language, or an integer or date-time not written as one. No editor shows the difference and no check sees it, but publishing would write it. A subject in a newer format than the app reads is refused as a newer app's (writtenByNewerApp), whose message asks for a reload.

  • Links on the catalog. sm:releaseDraft names a draft's release document, and sm:publishedRelease a release published from the instance. Like sm:newcomerCourse on the library's catalog, they belong to no shape, so CatalogV1 keeps them through every write. Only a link to a draft's place in the same instance is followed. A learner's app reads sm:publishedRelease in a creator's shared catalog to find newer versions of a release it added from a link, only in the instance the release's address names, and only those links in it (deck-library.md).

  • A draft is checked as a draft. Its deck, chapters and steps are checked against the draft shapes, which don't yet ask what only a published release needs; its cards and distractors as anywhere else (validation.md), on every write and in the instance's check. What no shape describes (how the release was made, its sources) is written as it is, and kept through every edit; the Studio's release screen writes it as the library's releases do (deck-library.md, studio.md). Of the classes another app gives a subject the draft reads by its shape, the draft keeps only those the subject's write would keep (shapes.md), so none of them stops an edit. The release published from it leaves the others out too. A draft names the release it was published as with sm:releasedAs, and is then no longer edited. An sm:releasedAs at an address no release can have (isPublishedReleaseUrl, as for the catalog's releases) is read as absent: the Studio neither links it nor asks it whether the release is public. Of several, one at a release's address is read.

  • Writes follow the write discipline. Making a draft puts each document only where none is (If-None-Match: *), the release document first, then links it from the catalog (If-Match, read and made again on a 412). A release document already there means the name is taken and nothing's written; the Studio tries the next name. Any later failure deletes what was written before the failure is shown, so no draft is left unlinked.

    An edit is one write of each document it changes, made only if the document is as it was read (If-Match; a new chapter's document, only where none is). When one changed elsewhere, it's made again on the draft as it is then, three times in all. An edit made from a read that another edit has overtaken is refused (changedElsewhere). Each document an edit changes is one whole PUT, If-Match: Community Solid Server's in-memory store cuts text short after a PATCH, and node-solid-server stores a boolean a PATCH inserts as false. A server with no strong ETag gets no If-Match, so there an edit made elsewhere meanwhile is written over.

    Deleting a draft removes its subjects from its documents, the release document last, deleting each document that then holds nothing else; subjects nothing of the draft leads to are another app's and kept with their document (keptDocuments). Then it deletes the draft's container and the ones above it (drafts/<name>/, drafts/) where they're then empty, then the link.

  • A release is frozen. It's written once, at library deck format 6, and describes its own series and publisher (deck-library.md). assemble makes a draft a release's text, with every subject moved to the release's address, @base that address, and its release time set. Publishing assembles the draft from the read its checks saw, not from its documents read again. A draft's version names that read, never only its documents' ETags: a document read again is a new read unless the pod answers 304. A server can give no ETag, or the same one for other content, so ETags alone can't show the draft is unchanged. A read since, or an edit, makes publishing at that version changedElsewhere.

  • Publishing a release (solidReleasePublisher.ts, studio.md) puts that text, as it is, at releases/<name>/v<N>.ttl of the instance, or in another folder the user chooses, in one PUT only where nothing is (If-None-Match: *). A 412 is releaseTaken, unless the document there states the same statements, its dcterms:issued and dcterms:modified aside, and no other draft of the instance names it: then publishing goes on from there. Next, only <release>.acl or <release>.acr (glossary), on the release's origin, gets public read and nothing else, and no other access control changes. Where a server names another one as the document's, such as the folder's, that one's left as it is and the release stays private. Then the catalog links it (sm:publishedRelease, If-Match, read and made again on a 412), and the draft names it (sm:releasedAs), If-Match on the version the draft was checked and assembled at (changedElsewhere). A failure after the PUT is finished by publishing again at the same address. The app never writes a release again, nor deletes it, and registers it in no type index: the catalog's link is how its author's releases are found.

The answer log

Every grade given in study is kept for the statistics (statistics.ts): activity by study day, streaks, how well reviews were remembered, in all and month by month (monthlyRetention), and the running total of prompts introduced (introducedOverTime). How many prompts are new, young and mature, and the reviews due ahead, come from the review states, not the log (srs.md): a review state says only where a card stands now, and the log is the history. Once a day has answers, a strip above the deck list says what the day came to (todayOf, statistics.md). The log is source data: nothing could rebuild it.

  • One document per study month for the whole instance, history/<YYYY-MM>.ttl (historyUrlOf, by the study day's month, so a day is never split). A year of statistics is twelve GETs whatever the number of decks; reading it again is a 304 for each month that didn't change. Only the month document's own subjects are its answers, by the cards' rule: a subject of another document, or at another spelling of its address, isn't one, and isn't removed as one. A document whose name isn't a month 01 to 12 of the days shiftStudyDay keeps in order isn't one of the log's (monthOfHistoryUrl). No read takes in a month after that of the day after tomorrow: no answer counted can be in it. The log's months are listed from one read of history/ alone (AnswerLog.months): a month's document is one of its own, so no folder below it is read. A month after that of the day after tomorrow is left out first. That day is by a boundary at midnight, the latest any gives, so the preferences aren't read. Then of more months than those of CHART_YEARS and a year more (MAX_LOG_MONTHS) only the newest are taken in, since each month taken in may be read. A later month listed never pushes out an earlier one. A guest's study whose log has as many months isn't moved or added to a Pod (guestStudyTooLarge): some of its months might be left behind. The today strip keeps a summary of each past month in the digest.

  • One subject per answer, #answer-<time>-<random> (for one added from a guest's study, followed by the id of the deck it was added to; answer.ts). It names:

    • the deck's catalog entry and the card it was given to; either may since be removed, and a removed deck's answers stay, as a removed deck;
    • the direction, and the SM-2 grade, whichever answer scale gave it;
    • when it was given, and the study day it counts toward, fixed then so a later day-boundary change doesn't move it;
    • the prompt's interval before (absent on its first answer, which introduced it) and after.

    An answer to a course question says how it was given (sm:answerMode sm:multipleChoice) and, when it was wrong, which wrong option was chosen (sm:chosenDistractor, the distractor in the deck's cards document). It's left out when that IRI couldn't be written: longer than a term may be, or not one Turtle writes as it is (chosenDistractorIn). A release's own address may be much shorter than the deck's, and the answer is logged without it. An answer given in study says neither, which means recalled. Since vocabulary 1.19 an answer may say how long it took, in milliseconds the app was shown. That's from the prompt to the answer revealed, or to the option chosen (sm:recallMillis), and from there to the grade (sm:gradeMillis), each left out above ten minutes. It may say the day the prompt was due before it (sm:priorDue, absent on a first answer), and the device's offset from UTC then, in minutes east of Greenwich (sm:utcOffsetMinutes). Each is optional, and an older app ignores them (migrations.md).

  • The intervals and due day are those of the scheduler that set them. The grade is always the SM-2 quality, but the interval before and after an answer and the day it was due come from what set the prompt's due day then (effectiveStates). Under FSRS-6 that's its fresh FSRS-6 state, else the SM-2 state its first FSRS-6 review is estimated from. The log's format doesn't change.

  • Added without reading (appendToDocument): one insert-only PATCH, with no precondition, since an answer names a subject no other writer does. Every server tested creates the document and its container when missing, and keeps every one of several concurrent inserts (e2e/pod/src/history.integration.test.ts). A guest's study added to an instance brings its answers the same way: a month's in one PATCH, or several where one would pass 64 KiB (appendAll). Each id is the guest's followed by the new deck's, so adding it again to the same deck changes nothing. Adding it to another deck (the guest's deck added anew) makes an entry of its own, never one naming two decks. A wrong option chosen that would be too long in the new deck's longer address is left out, not the answer. An answer to a card left out, whose IRI there would be too long, isn't added.

  • After the review, not in its way: recordReview saves the review state, then queues the answer, with its response times (statistics.md), to be added in the background. Each instance has its own queue, and another instance's answers never wait for a failed one. One that fails waits, with those of its instance after it, until that instance's next answer tries again, or something that reads or changes its log: the end of a study session in it, its statistics, resetting a day. An add the server hasn't answered within 10 seconds is given up and tried again later, which changes nothing if it was saved (APPEND_DEADLINE_MS). An answer refused before it's sent would be refused every time: by the write check (dataNotConforming), or for a term Turtle can't write as it is (unwritableTerm) or longer than a term may be (termTooLong). Only that answer is set aside, never logged, and those after it go on. So is one the pod refuses as a bad request (400, 413, 414 or 422) a third time. Any other failure, such as no answer from the pod, a failed login or a server error, is tried again: it says nothing of the answer, and those after it would fail alike. An answer still queued when the tab closes is lost; its review isn't.

  • Resetting the day removes that deck's answers of the day (removeDay: read, remove, save with If-Match, again on 412), and drops those still waiting to be added from the queue. Undoing an answer in a session removes that one answer by its id (removeAnswer, the same way), and drops it from the queue while it still waits there. A failed add may still have been saved, so only an answer no add was ever begun for is left out of removeAnswer (srs.md). An add given up on at its deadline that the pod saves only after the removal stays in the log. Nothing else removes answers.

  • A card moved to another deck leaves its answers behind. A Studio move never rewrites the log: past answers keep naming the source deck and card, and in the target the card's history starts again, though its review state may come along. A copy's history starts in the target; the original keeps its own.

  • Read whole by the Studio (loadAnswerLog): every month taken in (above), for a card's history, its lapses and the deck's leeches (studio.md). The statistics (getStatistics) read the months of their range. Both go through one cache (readLogMonths), which keeps each month's answers in the page with the version they were read at; a month is read again only once it changed (readMonthSince, a conditional GET). Months are read six at a time at most. A read adds to the cache and never replaces it; a month the log no longer lists is dropped (statistics.md). An answer counts only in its month's document. One whose study day is more than a day outside that month is left out (isOfStudyMonth; the day allows for the time zone), as is one whose study day isn't a real date. So is one outside 0100-01-04 to 9999-12-31, the days shiftStudyDay keeps in order (isOfStudyDayRange). A prior due day (sm:priorDue) that isn't a real date, or is outside that range, is dropped, and the answer kept. A read checks a number's datatype, not its range, so the numbers are bounded as they are read (answerFromRecord). An answer whose grade isn't a whole number from 0 to 5, or whose interval isn't a whole number of days, 0 or more, that a number holds exactly, is left out. An interval above the 36,500 days the app now caps at is kept: an answer written before that cap may carry one. A response time that isn't a whole number from 0 to ten minutes in milliseconds (MAX_RESPONSE_MILLIS), or an offset from UTC that isn't one from −840 to 840, is dropped, and the answer kept. A time from elsewhere then never makes a month's summary or the time studied anything but a number. The Studio names a deck's past answers by their card's id in its current cards document (deckAnswers), which a library upgrade may have moved.

  • Checked in the full check only (validation.md), since the current month changes every session.

The digest

digest.ttl lets a visit skip what hasn't changed. It holds only what Solid Memo learned of the other documents, each fact stamped with the version (ETag) of the document it was learned from (studyDigest.ts):

  • a receipt per document: at that version it conformed to the shapes (sm:conformedTo names the rules, a hash of the shape files the site was built with) and/or nothing in it was in an older format (sm:latestFormat);
  • a schedule per deck, from given versions of its cards and reviews documents: prompts due by study day (sm:dueOnDay "2026-10-01 12"), prompts never reviewed, and the reviews and introductions of the day it was computed on. With today's preferences they give the deck list the same counts as buildStudyQueue (srs.md). A review state whose sm:due is no real day isn't counted on any day, and a schedule with a sm:dueOnDay not as its shape has it is dropped and computed again. It names the direction, the day boundary and the scheduler it was computed with (sm:scheduledWith, the preferences' sm:studyScheduler), and holds only while all three are the deck's and the preferences' (switching scheduler writes no review);
  • a month summary per past study month of the answer log that the today strip looks back over, from a given version of its history/<YYYY-MM>.ttl (sm:summaryOf, sm:summarizedVersion). It holds each study day's answers, new cards, scored reviews and lapses (sm:studyDayCounts "2026-09-29 12 3 8 1"). It holds the month's reviews of young prompts and how many were remembered (sm:youngReviewCount, sm:youngRecalledCount), and how many recalled answers took each whole second (sm:recallSecondsCount "4 7", a minute or more counted at 60). The strip shows these and estimates the time left today from them (statistics.md). A summary needs no day boundary, and a month no longer looked back over is dropped. A summary is read only when its sm:summaryOf is a month's document, a path ending in history/<YYYY-MM>.ttl with no query or fragment. Each of its days must be a real date of that month, or a day either side, given once, and its counts have at most 15 digits. Any other is left out, made again from the month's answers and written over the one in the digest.
sequenceDiagram
    accTitle: Counting a deck through the digest
    accDescr: The app reads the digest, then asks for each deck's cards with the version the digest holds, and the pod answers 304 when nothing changed or 200 with the document when it did.
    participant App
    participant Pod
    App->>Pod: GET digest.ttl
    App->>Pod: GET decks/d.ttl If-None-Match: <its version in the digest>
    alt unchanged
        Pod-->>App: 304 — counts from the schedule, no check
    else changed (or no digest yet)
        Pod-->>App: 200 + the document — counts and check from it
        App->>Pod: PATCH digest.ttl (in the background)
    end
Loading
  • A stale digest is never wrong, only slow. Every fact is used only after the pod says its document is still at the stamped version. A document changed elsewhere is read and checked in full, and the digest repaired with what that read learned; nothing else keeps it up to date. A stored version is sent only as one entity tag of at most 512 characters. Any other counts as none, the wildcard * among them: the document is read in full, and what that read gives replaces it.
  • When a study session ends (End session, leaving the screen, or the page being hidden) the deck's schedule and its reviews document's receipt are brought up to date.
  • Writes are edits like any other (If-Match; write check). Changes learned while a write is under way go in the next one. On a 412 it's read and changed again, six times in all, waiting longer before each (50 ms, then 100 ms, …), since a page learning a check's documents writes the digest several times running. When the app or the pod refuses what a write says, its changes are written again one at a time, so only the refused one fails. Until one of them is written, when the pod refuses one alone with an answer it gave already, as it would every write over its quota, the rest fail with it. A failed write is dropped: the next visit learns it again. Each write is one edit of the document, made in time that grows with its subjects, not their square. What's dropped is removed from every subject it was read from, whatever that subject's name, as is any other subject that said what's written again, so none of it is read back.
  • Only the instance's decks. A deck's schedule and its documents' receipts are kept only when both documents are in the instance, or in a storage of the signed-in user's that holds it (the place rule). So is a document's check receipt. An instance attached from another's pod may name the user's own documents as a deck's: the deck list's counts of such a deck come from its documents read as no one, and go into no digest. The study statistics read a deck's documents as the user, and the same rule, applied where a schedule is kept, leaves what they learn of such a deck out of the digest. An instance in a folder of the user's own storage that's shared with write access to someone else keeps the documents there in a digest that person can read too, as it keeps the instance's other documents.
  • Read leniently. A subject that doesn't fit its shape is left out, and relearned. The digest isn't one of the documents an instance is checked by.
  • An entry is written new. Each entry has a subject of its own name in digest.ttl, and a write replaces what that subject says, whether the app read it as that entry or not. Another class, a value the entry's shape doesn't have, or a newer format isn't kept, so none of it can stop the entry from being written. A value that's a blank node stays, as a write can't name one to remove it; the app neither reads it nor checks it, so it stops no write either. Unlike the instance's other documents, the digest doesn't refuse to write over an entry a newer version of the app wrote: the digest is derived data, so the newer version learns what it needs again on a later visit.
  • Read only for what an instance can have. A receipt is read only for an address a document may be read at, and a schedule only for a deck of the instance's own catalog. At most one receipt is read for each fixed document, two for each deck, at the catalog's limit (MAX_CATALOG_LINKS), and one for each of the drafts' documents, at their limit together (MAX_DRAFT_DOCUMENTS_IN_ALL), and one schedule for each deck. Any other is left out, and removed at the next write. A write keeps to the same limits: past them, the entries it didn't change go first, the earliest first, so a full digest still takes what a visit learns.
  • Changes don't copy it. What a visit learns is made in place to the page's own copy of the digest, and the changes a write takes along are made to one copy of what it read. Learning a fact of each of many documents takes time that grows with the digest and the facts, not their product.
  • It is as good as the pod's ETags. Community Solid Server 6 stamps its ETags in whole seconds, so a document changed elsewhere in the same second as Solid Memo read it is taken for unchanged until it changes again (7 stamps milliseconds). The same holds for If-Match (below).
  • A pod without ETags gains nothing. node-solid-server (5.x, 6.0.0) gives no ETag on a read, so nothing is kept, and every visit reads everything.
  • The format update doesn't write the digest; what it says of the documents it writes is relearned on the next visit.

Decks as files

The Studio saves a deck as a file, and makes a deck of a file (studio.md): Turtle or JSON-LD, one deck to a file. The domain names its parts (deckFile.ts), and the DeckArchive port reads and writes it (solidDeckArchive.ts).

An export holds triples as the pod has them, at the pod's IRIs:

  • the deck's entry in catalog.ttl, its distribution and the agents it names as its creators, its card language (sm:deckCardLanguage) and picture hosts (sm:deckPictureHost) among them. A creator goes only when it's an agent as Solid Memo writes one: a foaf:Agent of no other class a shape describes or adds, and not the catalog (isCreatorAgent in ownership.ts). Another deck's entry, a dcat:Dataset, the catalog or any other node named as a creator stays behind, and so does the deck's dcterms:creator link to it. No subject that goes takes its sm:position along, nor its sm:completedChapters unless the progress goes too;
  • its cards (each sm:Card of its cards document) and the wrong options they name, retired ones too, with whatever another app said of them;
  • with the progress, the review states of those cards in its reviews document.

Nothing else of either document goes: a deck may name a document that holds more than the deck. Each of the two documents is read as the user only when it's the instance's (isInInstancePod), as a move or copy of cards reads its source. An instance attached from someone else's pod may name a document of the user's own. Any other is read as no one.

Nothing is rewritten: a deck still at an older format is exported at it. A JSON-LD file is flattened: every subject is a node of its @graph, and its @context is the prefixes the Turtle uses too (sm, dcterms, dcat and so on), written in full.

An import reads the file as the pod is read, with the same mappers:

  • the file must hold one deck (sm:Deck) that fits its shape;
  • its cards are the cards of its cards document, its review states those of its reviews document, of cards it holds;
  • an older format is brought up to date as it's read (migrations.md), and the screen says how many parts were. A deck, card or review state in a newer format than the app reads is refused (deckFileTooNew, not writtenByNewerApp, which refuses to save over pod data a newer version wrote), and nothing is written;
  • a subject of these kinds that can't be read is left out, and the screen says how many were;
  • relative IRIs are resolved against https://file.solid-memo.invalid/ and the file's name (DECK_FILE_BASE);
  • a JSON-LD context named by its address (or @import) is refused, as reading it would fetch that address. The parser reads the document as the check saw it, so a key named twice is the last one for both, and its document loader fetches nothing;
  • a JSON-LD context below the top level (in a term's definition, or on a node inside the document) is refused, as is a list of more than 8 contexts (deckFileUnreadable). The parser applies a term's context again at every use of the term, and builds each context from a copy of all the terms before it, so a small file of such contexts holds the tab for minutes. A file this app exports states its context once, at the top;
  • a JSON-LD context that defines a term by more than an IRI (an object, such as one with a @container) is refused (deckFileUnreadable). The parser reads the values of some such terms, a @graph container, in time growing with their square. A context may give only strings, for its terms and for keywords such as @vocab; a file this app exports states prefixes alone;
  • a JSON-LD @base or @vocab is refused (deckFileUnreadable) under the rule for a Turtle base. One whose path has a ., .. or empty segment is refused. So are those a node's contexts declare when, with the file's own address and each resolved against the one before, they come to more than 512 characters. The parser walks the whole base for each relative IRI it resolves, and the IRIs it gives can be far shorter than the base, so the limits below wouldn't bound the time. A file this app exports declares neither;
  • a JSON-LD term or prefix is refused (deckFileUnreadable) unless it's defined as a keyword or as an IRI with a scheme, a plain path and at most 512 characters. So are a node's contexts when their terms and values come to more than 4,096 characters together. The parser gives a term's IRI again at every use, resolving a relative one against the base, so a long one costs its length at every use, for an IRI that may be short. A file this app exports states short namespaces with a scheme;
  • a JSON-LD term, @base or @vocab is refused (deckFileUnreadable) when it's another term of the node's contexts, or a compact IRI whose prefix, the part before its first :, is one. The parser expands such a term through the other with no bound on how deep, so two terms defined through each other, or one through itself, never end. A term defined as one that names a keyword names that keyword too, which the checks below would read as a plain term. A file this app exports states each namespace in full. With the base bounded and each term defined in full, at most 512 characters, the limits below bound the time;
  • the parser reads the document as it streams, each object written again with its context first. A parser that held every node to the end would match each against every typed one, in time growing with the square of the nodes. It gets the text in parts of 4,096 characters, each in a task of its own, and no more after its first error, so a parse that fails leaves the tab free after the part it failed in;
  • a JSON-LD keyword given a value the parser reports as an error is refused (deckFileUnreadable) before it's parsed, under an alias too. These are an @id that's no string, or a second one in an object, and a @type that's no string or array of strings. So are an @index that's no string and a @reverse that's no object or holds a keyword. So are an @included member that's no node object, a @nest member that's no object or holds @value or @id, and a @list beside any key but @index. A @set object's members, and an array's in it, count as members of the keyword it sits under. The parser reports such an error and reads on, and each takes it far longer than a triple, which the bound on the work below doesn't count. As with the checks below, it covers the whole document, a @json literal too. A file this app exports holds none;
  • JSON nested deeper than 12 levels is refused (deckFileUnreadable), before anything else reads it: the JSON-LD parser takes time far beyond linear in the depth, and a file this app exports nests 5;
  • JSON-LD with more than 4,096 values that make no triple, or that sit in an array in another array, is refused (deckFileUnreadable) before it's parsed. A value makes no triple when it's null, an empty array or object, or a string, number or boolean where a node belongs, in @graph, @included or the top-level array. A value object whose @value is null counts, and the empty array of an @list, which is rdf:nil, doesn't. A @set object counts as the array it holds, under an alias too. The values of an array in another array outside a list may make triples, but the parser takes the longer over each the deeper the arrays nest. JSON-LD writes no array in an array but for a list of lists, which counts neither. A file this app exports holds none;
  • a JSON-LD RDF-star annotation (@annotation, or a term defined as it) or triple term (an @id, or a term defined as it, given an object or an array that holds one) is refused (deckFileUnreadable). The parser is also told to read no RDF-star: it holds the annotations of the top-level nodes to the end, copying all those before it at each, in time growing with their square. The check covers the whole document: a term one node's context defines as @id is refused given an object anywhere, even as a plain key of another node, and so are these keys inside a @json literal. A file this app exports holds neither;
  • a Turtle triple term (<<( s p o )>>), reified triple (<< s p o >>), annotation ({| ... |}) or reifier (~) makes the file not parse (deckFileUnreadable), with limits or with none. The parser is told to read no triple term, on either client. An annotation or a reifier gives one past that option, so the parse fails at the first triple that holds one. The parser would read triple terms nested a thousand deep, building each level, while the limits below count the triple that holds them once. A file this app exports holds none of them;
  • a file larger than DECK_FILE_LIMITS in solidDeckArchive.ts is refused (deckFileTooLarge), and nothing is written. The limits are 64 MiB of text, a million triples, and 256 Mi characters in the terms of those triples, which a prefix or a context can make far longer than the text. They leave a wide margin over a deck of tens of thousands of cards with progress, which the pod holds with no limit. A Turtle file is refused the same way when it declares its base more than 16 times or more than 4,096 prefixes. So is one whose base can grow past 512 characters or has an empty segment in its path. So is one with a . or .. segment, but in a relative path with no colon. So is one with an IRI longer than 512 characters, in a triple or a prefix, that's relative or may hold a . or .. segment, as written or escaped. The parser removes those segments as it resolves the IRI, in time growing with the square of its length. So is one nested more than 64 levels deep in collections, blank nodes, annotations or triple terms, which the parser holds memory for without making a triple to count. Its parse stops there, as it stops at the first triple past the limits. A declaration or a bracket quoted in a card's text doesn't count. So is a file with a term longer than 16,383 characters, as every document the app reads is, and a JSON-LD file with a string or key that long, which is refused before it's parsed. So is a JSON-LD file whose values take the parser more work than 26 units for each triple the limits allow, counted before it's parsed. Each value, an array element or object member, takes 8, or 2 when it's a string, number or boolean given to @id, @type, @value, @language or @direction. A member under a key that's no keyword takes 2 more, and any other string, number or boolean 4 more. Every value takes 1 more for each container above it, and 4 more for each array it sits in directly in another, a @set object counting as its array. The parser takes time over each value, whether it makes a triple or not, and the more the deeper it sits. A file this app exports takes some 20 to 30 for each triple, the more the more of its literals have a language or a datatype. So such a file may be refused with somewhat fewer triples than the limits allow, still more than a deck of tens of thousands of cards holds. A file of values that make few triples or none may still take the parser about half as long again as one of the most triples allowed. A release file the Studio opens is held to a release's limits (deck-library.md);
  • a triple with a term Turtle can't write as it is is left out (below).

The deck is then written as a new deck of the instance (importedDeck). It keeps the file's deck id, so a deck exported, removed and imported again comes back at its URLs, and the log's answers name it again. It takes a fresh id when the instance has a deck by that id or one using a document of that name, or when the id or its distribution's (<id>-cards) is already a subject of the catalog. So does an id the app wouldn't give (deck-…), so no deck lands on #catalog, a group or an agent. Its cards keep their ids.

Only what Solid Memo knows of the deck and its cards is written, as any deck: triples another app put there are in the file, but not imported. Each card names its wrong options with sm:distractor and schema:suggestedAnswer, each typed sm:Distractor and schema:Answer. Each review state names its card in the new cards document (sm:reviewOf), its direction and sm:sm2. Its FSRS-6 states come too, as the app's own; a state of another scheduler isn't imported. The deck needs no type-index registration of its own (Registrations). The writes follow the write discipline: the cards document is created (If-None-Match), the reviews document written, and then the deck's entry added to the catalog, each checked against the shapes.

UI gaps

What the data model holds that Solid Memo's screens don't edit. Most of it's shown in Solid Memo; the Studio closes the gaps one by one.

  • Edited in the Studio:
    • a deck's authors and license, and its course progress (a chapter marked not done, the course restarted);
    • the instance's name, and the catalog's description and license;
    • a card's wrong options and review state (forgotten, or given a due day), and the deck a card is in (moved or copied to another);
    • edits of many cards at once, and several library copies upgraded at once;
    • a deck exported to a file or imported from one;
    • a draft of a release: what it says of itself, a course's chapters, steps and questions and their order, and its cards' wrong options.
  • Shown only:
    • the answer log, as statistics, and in the Studio as a card's history, the wrong options chosen, lapses and leeches;
    • the schedule in the digest, as counts, and in the Studio as a forecast;
    • the check of the shapes, in developer mode, and in the Studio as a deck's or the instance's health;
    • a draft's release check, and a preview of its listing in the library.
  • Not shown: a catalog's dcterms:modified, which the app keeps but never writes; a library copy's release provenance beyond its authors, license and sources.

Write discipline

  • Writes go only where Solid Memo writes. Every pod write passes the pod fence (boundaries.md), which refuses, before anything is sent, a write to an address that's unsafe to write: one a server might read as another, or an access control or metadata resource (.acl, .acr, .meta). No access control is written but a release's own, by the release publisher (a resource without its own ACL inherits its ancestors' access; a malformed one replaces that inheritance and can lock the owner out (WAC) or expose data). Otherwise access control stays whatever the user's server dictates.

  • No write holds a term Turtle can't write as it is. Such a term is an IRI with a control character, a space or one of <>"{}|^`\. So is a blank node label or a language tag outside Turtle's grammar, a language subtag over 8 characters, which the pod's parser refuses, text typed rdf:langString or rdf:dirLangString without a language, or a quoted triple. So is text typed rdf:dirLangString without a base direction or with one other than ltr or rtl, and a direction on any other literal. JSON-LD can hold such a term, and the writers don't escape it, so a > would end an IRI and the rest be read as statements no check saw. A JSON-LD value with a @direction but no @language is such a term too. A PATCH, a PUT, an insert-only PATCH, a release's Turtle and an export are refused with unwritableTerm before anything is sent (writableTerms.ts). An imported deck leaves such triples out; a release read from a file is refused, as a draft keeps its triples as they are.

  • No write holds a term longer than 16,383 characters, as no read accepts one (deck-library.md). The write is refused with termTooLong before anything is sent. A write gives a blank node 32 characters of room for the prefix a parser puts before its label (isTermTooLong). A Turtle read gives each blank node a short label of its own (blankNodeNamer), so the label it writes back is short and doesn't grow with each save. A JSON-LD read keeps its labels and writes them back as they are, so it holds a label to the bound with the same room as a write (BlankLabels). Either way, a term a read keeps never blocks a later save of the whole document, and what the app writes it can read again. A record brought up from an older format in memory is held to the bound as it would be written, and one that would pass it is read as not fitting its shape (migrations.md). A document saved before the bound may hold a longer text, such as a card's back, a step's theory or a catalog entry's keywords. Its read now fails with a ReadLimitError. The app has no way to shorten the text, so it has to be edited outside the app.

  • What is read can be written back. An IRI that new URL refuses, such as <http://[x>, is still an IRI to the Turtle parser, but the client library writes no such IRI. So no value the app reads into its models holds one (readIris in records.ts): a deck's theme or source, a card's release or subject, a draft's field, or the catalog's publisher, which a new deck group takes. The next write of a subject leaves such a value out, but a value the write keeps stays as it is (setIriAll): a link of the catalog or of a deck group, a deck entry's sm:completedChapter, and a card's sm:fromRelease. A draft that states one is refused as one that states a value otherwise than the Studio reads it (draftHiddenValue), so it is never published with it. A literal with a base direction (RDF 1.2, "…"@ar--rtl) that another app wrote is kept with its language and direction, and written back as it was read, in a PATCH and in a PUT alike (graphsOf). A Studio draft keeps it too, as it is edited and published, and so does a deck's export, in Turtle and in JSON-LD (@direction). The app writes no direction of its own and reads no such literal as text in a language.

  • A date is written as xsd:dateTime spells it. A year past 9999 or before 0 has no plus sign and no leading zeros beyond four digits (xsdDatetime in records.ts), as 12345-01-01T00:00:00.000Z or -0001-01-01T00:00:00.000Z. So a date the app read is written back and passes the write check.

  • Mutations always follow read → modify → save (datasets.ts: readDataset or getSolidDatasetOrNull, then saveDataset). The save sends a PATCH of the delta, or for a large edit one PUT of the whole document as read and edited (below), so unknown triples survive. Only brand-new documents are saved from createSolidDataset(). The one exception is the answer log: answers are added unread, with an insert-only PATCH.

  • An edit of many subjects is made to the dataset at once. Such edits are a release's cards written, cards removed, the deck groups and positions of a rearranged deck list, and cards, catalog entries and review states brought to this app's format (setThings and removeThings in client/rdf.ts, editOf in datasetEdit.ts). A subject at a time would copy the whole document at each, in time growing with the square of its subjects. A list of values of one subject, such as a card's distractors or the catalog's links to its decks, is set in one call too (setIriAll and setStringAll of a subject's builder). An add at each value would copy the list so far. The edit and its save then take time that grows with the document.

  • A card moved to another deck in the Studio is written afresh in the target with only what Solid Memo knows of it. Its subject and its wrong options' are removed from the source, triples another app put on them included. A copy leaves those triples in the source and doesn't carry them over.

  • A palette's color set is written afresh too, with only its colors: its shape is the one closed shape, so a triple another app added would have every later save refused. It's written only at a subject that's a color set and nothing else, which no other palette names (theme.md). For the same reason, a palette, and any other subject written through recordThing, drops the color set's class if another app gave it one. It drops every other class that isn't its own and that a shape, or the DCAT-AP profile, asks something of (shapes.md). The checked edits that change a subject in place drop them too: a deck's card language or completed chapters, the deck tree's catalog on any edit of the tree, and the preferences when the Connected screen is marked seen. The deck tree leaves a catalog a newer app wrote as it is when the edit leaves its links alone. A class no shape asks anything of stays, up to the number of classes the check reads a subject by; the ones past that go too, and so does a value of rdf:type that is no IRI.

  • Every write states what it expects to find, as an HTTP precondition:

    • an edit is sent with If-Match: <the ETag the document was read with>; if the document changed since, the pod answers 412 and nothing is written. An edit is a PATCH, or one PUT of the whole document when the PATCH would be larger than 64 KiB (a PATCH larger than 100 kB fails on node-solid-server, and a format update of a large deck exceeds it). Without If-Match (no strong ETag, below), such a PUT undoes a change made elsewhere since the read. Two edits are always one PUT (saveDataset's whole): stating the language of a deck's untagged card sides (stateCardLanguages), and the Studio's bulk edits of cards (editCards, studio.md). Community Solid Server's in-memory store cuts a document short after a PATCH holding text beyond ASCII. A save of the preferences is always one PUT too, since node-solid-server stores a boolean a PATCH inserts as false (the preferences hold two, the developer settings and "Not now" to switching to FSRS-6);
    • a creation is sent with If-None-Match: * (by the Solid client library, behind client/resources.ts, for datasets and containers, by the copier for files); had something appeared there meanwhile, 412;
    • deleting a document read before sends If-Match too. Every removal of Solid Memo's data from a document (deleting an instance, a deck or a draft, or taking back what a failed creation wrote) goes through removeOwned in datasets.ts. It has a rule for what of each kind of document is Solid Memo's (ownership.ts). It reads the document afresh, takes out Solid Memo's subjects of that kind, less any a newer version of the app wrote, and the blank nodes only they name. It deletes the document only when nothing else is left in it; otherwise it writes back what's left: a PATCH of DELETE DATA, or, where a blank node goes, one PUT of the rest, each If-Match its read. A document that isn't RDF, or holds nothing of Solid Memo's, is kept and nothing is sent. On a 412 it reads and removes again, once; a second 412 is changedElsewhere. Where the pod gives no strong ETag, the delete and the PATCH go without If-Match; a PUT, or a PATCH too large to send as one, isn't sent, and the document is kept as it is. A deck's cards or reviews document is removed from only when it's the deck's (where an instance's documents are). A deck another tab adds meanwhile is missed, and keeps the folder in place.

    An edit or a delete is matched to its read by the document's address as a request sends it (isSameUrl), so one spelled another way than the pod answered with still carries the If-Match of that read.

    A 412 surfaces as a PreconditionFailedError naming the document ("changed elsewhere … Reload and try again"). Nothing retries on its own, except the writes that re-apply a change to the document as it is then:

    • the digest;
    • an edit of the deck groups, and the Studio's edits of metadata (a deck's authors and license, the instance's name, the catalog, a course's chapters completed), three times in all;
    • a bulk edit of cards, planned again on the cards as they are, three times in all, stopping when that plan isn't the one previewed.

    A grade's edit of the reviews document is made from the document as last read or written, at the version that left (srs.md); on a 412 it's read and graded again, once. Weak ETags (W/"…") are never sent in If-Match, whose comparison is strong; a document the pod gives no ETag is written without If-Match. When the pod answers a write made on a precondition (If-Match, or If-None-Match: *) with a strong ETag, the app keeps the written dataset at that version, as a read keeps what it read. The next edit sends If-Match with it, and the next read If-None-Match. Without it (Community Solid Server 7 answers a PATCH with none), nothing is kept, and the next read downloads the document. Either way the read that edit was made from is out of date. A later save from it, of the dataset saved or another edit of the same read, is refused with a PreconditionFailedError before anything is sent, and so is a delete made on it. Sent without If-Match, either could undo the first save and a change made elsewhere since. A read saved to another document isn't out of date where it was read: an edit or delete of it there still sends its If-Match. A read without a strong ETag has no precondition to lose: an edit of it is still written again without If-Match, and deleted without one. node-solid-server gives no ETag on a read and ignores If-Match; 5.7.4 ignores If-None-Match: * too, which 5.8.8 and 6.0.0 enforce. There no edit is conditional: a PATCH still keeps a change made elsewhere, a large edit's PUT doesn't. Community Solid Server 6's whole-second ETags miss a change made in the same second as the read (as in the digest). The end-to-end tests hold all of this against real servers, that one included (testing.md).

  • An edit's PATCH body is written by Solid Memo (patchBody in client/sparqlUpdate.ts, sent by writeDocument in client/resources.ts), not by @inrupt/solid-client: one triple a line, a space before each .. node-solid-server's parser fails on a triple whose closing . touches the term before it (<#a> <#b> 1.}), as @inrupt/solid-client writes them. That server finds a decimal only as JavaScript spells its number (1, 2.5), though it serves a whole one as 1.0 and another app may have written 2.50. A PATCH it refuses (409) for a deletion spelled as read is sent once more, its deleted decimals so spelled. A triple gone is refused the second time too; one found then holds the same number.

  • A document is downloaded once while it is unchanged, though a screen asks for it several times (a deck's cards for its study queue, the format check and the data check). A read already under way is shared, and a document read before is asked for with If-None-Match: <its ETag>; on 304 the dataset read then is returned (datasets are immutable). A write to the document forgets both, unless it kept what it wrote at the version the pod answered with (above). It's kept in memory for the open page only. Logged in, the browser's own cache doesn't do this: without it a login downloaded every deck three times. That cache is never asked (cache: "no-store"), since it may keep a document the pod gives a modification time and no Cache-Control for days, and answer a plain read with it.

  • Reading builds the dataset in one pass (linearDataset.ts): @inrupt/solid-client copies the whole graph for every quad, which took 9 s for a deck of 3,000 cards.

  • 404 is a normal state for not-yet-created documents; repositories treat it as empty, not as an error.

  • What Solid Memo didn't write, it doesn't delete or unlink. A write touches only the triples it changes, and a delete only resources Solid Memo knows it wrote (deleting an instance). A guest's deck may be added to a newly created instance: when that fails before the deck's entry names them, its cards and reviews documents are deleted, each as read, with If-Match. Only a folder Solid Memo made whole, at a URL it found free, and nothing names yet is deleted recursively: the guest's study moved into a new instance, when that fails half-way or a closed tab leaves it behind. A folder a closed tab left that the type index now names, or that holds anything the move didn't copy, isn't deleted.

  • An update writes each document in one edit, held to its read. The format update and the library upgrade write each document where it is, in one edit made only if the document is still at the version read (If-Match). The edit is made from that same read or, for an upgrade's cards, from the changes planned on it (migrations.md). A document whose write fails is as it was, and nothing is put back. No write puts an older format over a subject a newer version of the app wrote (migrations.md).