[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78F9PSTXR4526K32FDWAR1P":3,"skill-same:01M78F9PSTXR4526K32FDWAR1P":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M78F9PSTXR4526K32FDWAR1P","solid-scale-and-sharding",null,"Use when deciding how to lay out an app's data across pod documents — how many documents, when to split, where collection data goes (notes, bookmarks, messages, chat) — or when reads have grown slow (a flat container heading past hundreds of members, a monolithic file re-downloaded on every view, wanting SPARQL over a pod). Covers the one-document default, permission-driven splitting, interop with existing Solid data models, and the hard limits.","jeswr\u002Fsolid-sdk","jeswr","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F63333554?v=4","01M78F8AE112CQ0KHFC3R0Z8SJ","Jesse Wright","01M78F8AERJX4YWDA1S4BMF74V",2,"MIT","https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Fapps\u002Fissues\u002F.claude\u002Fskills\u002Fsolid-scale-and-sharding\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: solid-scale-and-sharding\ndescription: >-\n  Use when deciding how to lay out an app's data across pod documents — how many documents,\n  when to split, where collection data goes (notes, bookmarks, messages, chat) — or when reads\n  have grown slow (a flat container heading past hundreds of members, a monolithic file\n  re-downloaded on every view, wanting SPARQL over a pod). Covers the one-document default,\n  permission-driven splitting, interop with existing Solid data models, and the hard limits.\n---\n\n# Solid document layout, scale, and sharding\n\nA Solid pod is a **document store, not a query engine**. There is no `WHERE`, no `ORDER BY`, no\n`LIMIT` you can push to the server. Layout is therefore a design decision you make up front —\nand the first rule is to keep it simple.\n\nThis skill assumes the house stack in [`AGENTS.md`](..\u002F..\u002FAGENTS.md): read\u002Fparse with\n`@jeswr\u002Ffetch-rdf`, typed access via `@solid\u002Fobject` + `@rdfjs\u002Fwrapper`, mutations through\n`TermWrapper` subclasses, conditional `PUT` writes. Never hand-built triples, never\n`@inrupt\u002F*` \u002F `@ldo\u002F*`.\n\n## Rule 1 — start with one document\n\n**The main reason to split data across documents is access control**: permissions apply\nper-resource, so data with different audiences needs different documents. The corollary: while\nyour app's data all shares one audience — which is normal in early development — **put it all\nin a single document**. One read, one write, one ETag, trivially consistent, easy to inspect.\n\nSplit when (in priority order):\n\n1. **Permissioning** — part of the data needs a different audience (shared with another user,\n   public, app-private). Split along the permission boundary, nothing else.\n2. **Interop** — an existing Solid data model prescribes a layout (see Rule 2); follow it.\n3. **Size\u002Fperformance** — the single document is genuinely too big to re-download\u002Fre-PUT per\n   interaction (a deployed bookmark collection famously hit ~12 MB\n   ([forum 6886](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fsocial-bookmarking-as-an-example-where-we-need-queries-instead-of-documents\u002F6886))).\n   This comes *last* — don't pre-shard for scale you don't have.\n\n## Rule 2 — reuse existing Solid data models before designing a layout\n\nIf the functionality you're building exists in the Solid ecosystem, **use its data model and\nstorage pattern** so your app interoperates with deployed apps rather than creating a private\nsilo:\n\n- **Chat**: follow the [chat client-to-client specification](https:\u002F\u002Fgithub.com\u002Fsolid\u002Fchat) —\n  same model and layout as existing Solid chat apps.\n- **Shapes for common domains** — chat, bookmarks, address books, people, events, meetings,\n  issue tracking — are in the\n  [Solid SHACL Shapes Catalogue](https:\u002F\u002Fgithub.com\u002Fsolid\u002Fshapes) (`chat.ttl`, `bookmark.ttl`,\n  `address_book.ttl`, …). Conform to them.\n- Survey what deployed apps do: [solidproject.org\u002Fapps](https:\u002F\u002Fsolidproject.org\u002Fapps).\n\nSee `docs\u002Fdata-modelling.md` in this repo for vocabulary selection; this rule is about\n*document layout* matching the ecosystem.\n\n## When you do split: shard along meaningful boundaries\n\nOnce a split is justified, keep each container to **hundreds of members, not thousands** —\nlisting cost grows with membership, and a 1,411-document container took >1 s to list and ~3\nminutes to load fully\n([forum 3320](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fstate-of-the-art-for-querying-large-containers\u002F3320)).\n\n| Strategy | Layout | Use when |\n|---|---|---|\n| By permission boundary | `shared\u002F\u003Cid>.ttl` vs `private\u002Fnotes.ttl` | Always first — mirrors who can see what |\n| By date | `messages\u002F2026\u002F06\u002F\u003Cid>.ttl` | Append-mostly time series (chat, logs); gives natural pagination |\n| By hash | `bookmarks\u002Fa3\u002F\u003Cid>.ttl` | Random access by id, no time dimension; fixed fan-out |\n\n- **Container URLs end in `\u002F`** — always.\n- Derive paths from the pod root discovered via `pim:storage` (`agent.storageUrls` — if there\n  are several, the user chooses), under a path your app owns.\n- Create intermediate containers explicitly; don't assume deep paths auto-create everywhere.\n\n## Finding data again: the Type Index\n\nUse the **Solid Type Index** as the locator — register each class of data your app stores\n(`solid:forClass` → `solid:instance`\u002F`solid:instanceContainer`) and look data up the same way.\nThat is its job, it is the ecosystem's shared discovery mechanism, and it covers most needs —\nsee the companion `solid-type-index` skill for the read\u002Fwrite\u002Fbootstrap implementation.\n\nOnly if your UI needs ordered, field-level access the Type Index cannot express (sort by date\nacross shards, filter by tag) keep a *small* app-maintained summary resource alongside the data\n— update it in the same read-modify-write cycle as the record, through a `TermWrapper`\nsubclass, and treat it as rebuildable from a container walk. Prefer not to need one.\n\n## Querying: keep expectations low\n\nThere is no server-side SPARQL on standard pods. If you genuinely need ad-hoc queries across\npod documents, [Comunica](https:\u002F\u002Fcomunica.dev\u002F) can evaluate SPARQL client-side by traversing\nlinks — but it is **slow and rough; not a robust foundation**. Keep it for exploration and\none-off reads, never on a render-blocking path. Design reads around your layout (Rules 1–2 +\nthe Type Index) instead.\n\n## Hard limits to design around\n\n| Limit | Implication | Evidence |\n|---|---|---|\n| No server-side SPARQL | All filtering\u002Fsorting is client-side | [forum 3320](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fstate-of-the-art-for-querying-large-containers\u002F3320) |\n| Container listing is membership-only, no LIMIT\u002Foffset | You get the whole `ldp:contains` set; paginate via layout (date shards), not the listing | same |\n| `glob` removed | No bulk child-content reads; the old extension OOM'd servers | same |\n| ETags inconsistent (legacy NSS) | `If-Match` may be unavailable — handle a `null` etag | same; see `solid-server-matrix` |\n| One big file at scale | Re-downloaded + re-PUT whole on every change | [forum 6886](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fsocial-bookmarking-as-an-example-where-we-need-queries-instead-of-documents\u002F6886) |\n\nN3 Patch for partial updates: servers advertising `PATCH` accept it, but no sanctioned library\nbuilds patch bodies yet and hand-building them is banned — conditional `PUT` until one ships\n(`AGENTS.md` §Writing data).\n\n## Decision checklist\n\n1. **Does any of the data need a different audience?** No → one document; stop here.\n2. **Is there an existing Solid model for this domain** (chat, bookmarks, contacts)? Yes →\n   follow its spec\u002Fshape and layout.\n3. Split along the permission boundary; shard by date\u002Fhash only when a container would\n   otherwise grow past hundreds of members.\n4. Register every stored class in the **Type Index**; look data up through it.\n5. Resist client-side SPARQL on hot paths; design reads around the layout.\n","# Solid document layout, scale, and sharding\n\nA Solid pod is a **document store, not a query engine**. There is no `WHERE`, no `ORDER BY`, no\n`LIMIT` you can push to the server. Layout is therefore a design decision you make up front —\nand the first rule is to keep it simple.\n\nThis skill assumes the house stack in [`AGENTS.md`](..\u002F..\u002FAGENTS.md): read\u002Fparse with\n`@jeswr\u002Ffetch-rdf`, typed access via `@solid\u002Fobject` + `@rdfjs\u002Fwrapper`, mutations through\n`TermWrapper` subclasses, conditional `PUT` writes. Never hand-built triples, never\n`@inrupt\u002F*` \u002F `@ldo\u002F*`.\n\n## Rule 1 — start with one document\n\n**The main reason to split data across documents is access control**: permissions apply\nper-resource, so data with different audiences needs different documents. The corollary: while\nyour app's data all shares one audience — which is normal in early development — **put it all\nin a single document**. One read, one write, one ETag, trivially consistent, easy to inspect.\n\nSplit when (in priority order):\n\n1. **Permissioning** — part of the data needs a different audience (shared with another user,\n   public, app-private). Split along the permission boundary, nothing else.\n2. **Interop** — an existing Solid data model prescribes a layout (see Rule 2); follow it.\n3. **Size\u002Fperformance** — the single document is genuinely too big to re-download\u002Fre-PUT per\n   interaction (a deployed bookmark collection famously hit ~12 MB\n   ([forum 6886](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fsocial-bookmarking-as-an-example-where-we-need-queries-instead-of-documents\u002F6886))).\n   This comes *last* — don't pre-shard for scale you don't have.\n\n## Rule 2 — reuse existing Solid data models before designing a layout\n\nIf the functionality you're building exists in the Solid ecosystem, **use its data model and\nstorage pattern** so your app interoperates with deployed apps rather than creating a private\nsilo:\n\n- **Chat**: follow the [chat client-to-client specification](https:\u002F\u002Fgithub.com\u002Fsolid\u002Fchat) —\n  same model and layout as existing Solid chat apps.\n- **Shapes for common domains** — chat, bookmarks, address books, people, events, meetings,\n  issue tracking — are in the\n  [Solid SHACL Shapes Catalogue](https:\u002F\u002Fgithub.com\u002Fsolid\u002Fshapes) (`chat.ttl`, `bookmark.ttl`,\n  `address_book.ttl`, …). Conform to them.\n- Survey what deployed apps do: [solidproject.org\u002Fapps](https:\u002F\u002Fsolidproject.org\u002Fapps).\n\nSee `docs\u002Fdata-modelling.md` in this repo for vocabulary selection; this rule is about\n*document layout* matching the ecosystem.\n\n## When you do split: shard along meaningful boundaries\n\nOnce a split is justified, keep each container to **hundreds of members, not thousands** —\nlisting cost grows with membership, and a 1,411-document container took >1 s to list and ~3\nminutes to load fully\n([forum 3320](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fstate-of-the-art-for-querying-large-containers\u002F3320)).\n\n| Strategy | Layout | Use when |\n|---|---|---|\n| By permission boundary | `shared\u002F\u003Cid>.ttl` vs `private\u002Fnotes.ttl` | Always first — mirrors who can see what |\n| By date | `messages\u002F2026\u002F06\u002F\u003Cid>.ttl` | Append-mostly time series (chat, logs); gives natural pagination |\n| By hash | `bookmarks\u002Fa3\u002F\u003Cid>.ttl` | Random access by id, no time dimension; fixed fan-out |\n\n- **Container URLs end in `\u002F`** — always.\n- Derive paths from the pod root discovered via `pim:storage` (`agent.storageUrls` — if there\n  are several, the user chooses), under a path your app owns.\n- Create intermediate containers explicitly; don't assume deep paths auto-create everywhere.\n\n## Finding data again: the Type Index\n\nUse the **Solid Type Index** as the locator — register each class of data your app stores\n(`solid:forClass` → `solid:instance`\u002F`solid:instanceContainer`) and look data up the same way.\nThat is its job, it is the ecosystem's shared discovery mechanism, and it covers most needs —\nsee the companion `solid-type-index` skill for the read\u002Fwrite\u002Fbootstrap implementation.\n\nOnly if your UI needs ordered, field-level access the Type Index cannot express (sort by date\nacross shards, filter by tag) keep a *small* app-maintained summary resource alongside the data\n— update it in the same read-modify-write cycle as the record, through a `TermWrapper`\nsubclass, and treat it as rebuildable from a container walk. Prefer not to need one.\n\n## Querying: keep expectations low\n\nThere is no server-side SPARQL on standard pods. If you genuinely need ad-hoc queries across\npod documents, [Comunica](https:\u002F\u002Fcomunica.dev\u002F) can evaluate SPARQL client-side by traversing\nlinks — but it is **slow and rough; not a robust foundation**. Keep it for exploration and\none-off reads, never on a render-blocking path. Design reads around your layout (Rules 1–2 +\nthe Type Index) instead.\n\n## Hard limits to design around\n\n| Limit | Implication | Evidence |\n|---|---|---|\n| No server-side SPARQL | All filtering\u002Fsorting is client-side | [forum 3320](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fstate-of-the-art-for-querying-large-containers\u002F3320) |\n| Container listing is membership-only, no LIMIT\u002Foffset | You get the whole `ldp:contains` set; paginate via layout (date shards), not the listing | same |\n| `glob` removed | No bulk child-content reads; the old extension OOM'd servers | same |\n| ETags inconsistent (legacy NSS) | `If-Match` may be unavailable — handle a `null` etag | same; see `solid-server-matrix` |\n| One big file at scale | Re-downloaded + re-PUT whole on every change | [forum 6886](https:\u002F\u002Fforum.solidproject.org\u002Ft\u002Fsocial-bookmarking-as-an-example-where-we-need-queries-instead-of-documents\u002F6886) |\n\nN3 Patch for partial updates: servers advertising `PATCH` accept it, but no sanctioned library\nbuilds patch bodies yet and hand-building them is banned — conditional `PUT` until one ships\n(`AGENTS.md` §Writing data).\n\n## Decision checklist\n\n1. **Does any of the data need a different audience?** No → one document; stop here.\n2. **Is there an existing Solid model for this domain** (chat, bookmarks, contacts)? Yes →\n   follow its spec\u002Fshape and layout.\n3. Split along the permission boundary; shard by date\u002Fhash only when a container would\n   otherwise grow past hundreds of members.\n4. Register every stored class in the **Type Index**; look data up through it.\n5. Resist client-side SPARQL on hot paths; design reads around the layout.\n",{"name":5,"description":7},"main","5482abfe2666cc12f835fe360e8fad1f1e1dea8c","apps\u002Fissues\u002F.claude\u002Fskills\u002Fsolid-scale-and-sharding",0,"https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk","https:\u002F\u002Fgithub.com\u002Fjeswr","jeswr.org\u002F#me","@solid Lead @theodi | PhD Candidate @OxfordHCC\r\n\r\n","2026-11-15 05:20:24",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add jeswr\u002Fsolid-sdk --skill solid-scale-and-sharding",{"tool":39,"command":40},"bunx","bunx skills add jeswr\u002Fsolid-sdk --skill solid-scale-and-sharding",{"tool":42,"command":43},"pnpm","pnpm dlx skills add jeswr\u002Fsolid-sdk --skill solid-scale-and-sharding","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Fapps\u002Fissues\u002F.claude\u002Fskills\u002Fsolid-scale-and-sharding\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M78FNRF6EV6SKPEYRZ6JTTQ3","storage-conformance","Work on @jeswr\u002Fstorage-conformance, the shared storage conformance suite package in the Solid SDK workspace.","https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Ftools\u002Fstorage-conformance\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M78FNMS7HQGD9EE43WAFEW6A","fetch-rdf-engine-tests","Maintain fetch-rdf's real Node WASM parser integration tests without introducing a reverse engine dependency in fetch-rdf.","https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Ftools\u002Ffetch-rdf-engine-tests\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M78FNK5M6ASAR3909JT6BZV1","alpha","Use when checking fixtures, including folded YAML descriptions.","https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fcheck-skills\u002Fvalid\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M78FNGATR8F4N09HWSFVWBAF","widget","Use when testing package skills: YAML quoting works.","https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fcheck-skills\u002Fvalid\u002Fpackages\u002Fwidget\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M78FN9M05GCHYTK848SSMN9R","web-seo","Use when improving technical and entity SEO for a modern personal, portfolio, documentation, or marketing site, including crawlable HTML, canonical metadata, sitemap and robots, Person\u002FProfilePage JSON-LD, Core Web Vitals, and honest ranking expectations.","https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Fskills\u002Fweb-seo\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M78FN5ANETMSPMEFACSJ7JMC","solid-wac","Use when implementing or auditing Solid server WAC authorization, ACL creation and inheritance, auxiliary-resource escalation, method-to-mode mapping, 401 versus 403 challenges, WAC-Allow, or defensive typed ACL parsing with @solid\u002Fobject and @rdfjs\u002Fwrapper.","https:\u002F\u002Fgithub.com\u002Fjeswr\u002Fsolid-sdk\u002Fblob\u002Fmain\u002Fskills\u002Fsolid-wac\u002FSKILL.md",[],[]]