Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions .agents/skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,14 @@ tarball integrity are recorded in *pnpm-lock.yaml*. There are no checked-in
skill copies. *.claude/skills* points to this directory; pnpm also links the
same dependency skills into *.crush/skills/*.

| Git development dependency | Skills | Source |
| --------------------------- | ------------------------------------------- | -------------------------- |
| `@open-circle/agent-skills` | `formisch`, `valibot` | [open-circle/agent-skills] |
| `@chillicream/agent-skills` | `graphql-schema-design` | [ChilliCream/agent-skills] |
| `relay-github-root` | `relay-best-practices`, `relay-performance` | [facebook/relay] |
| `@dahlia/sacho` | `sacho` | [dahlia/sacho] |
| Git development dependency | Skills | Source |
| --------------------------- | ------------------------------------------- | ---------------------------------- |
| `@open-circle/agent-skills` | `formisch`, `valibot` | [open-circle/agent-skills] |
| `@chillicream/agent-skills` | `graphql-schema-design` | [ChilliCream/agent-skills] |
| `relay-github-root` | `relay-best-practices`, `relay-performance` | [facebook/relay] |
| `@dahlia/sacho` | `sacho` | [dahlia/sacho] |
| `modern-web-guidance` | `modern-web-guidance`, `chrome-extensions` | [GoogleChrome/modern-web-guidance] |
| `@leonxlnx/taste-skill` | `design-taste-frontend` | [leonxlnx/taste-skill] |

The pinned skill contents match the latest upstream versions checked during
this migration. ChilliCream is pinned to the last change to its GraphQL schema
Expand All @@ -38,3 +40,5 @@ updated source approval in *pnpm-workspace.yaml* together.
[ChilliCream/agent-skills]: https://github.com/ChilliCream/agent-skills
[facebook/relay]: https://github.com/facebook/relay
[dahlia/sacho]: https://github.com/dahlia/sacho
[GoogleChrome/modern-web-guidance]: https://github.com/GoogleChrome/modern-web-guidance
[leonxlnx/taste-skill]: https://github.com/leonxlnx/taste-skill
43 changes: 43 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,10 +45,35 @@ To be released.

### GraphQL APIs

- Added `Resource.currentRevision`, `Resource.revisions`, newest first,
`Resource.revision(sequence:)`, and the `ResourceRevision` node, which
return the saved revisions of a resource, including those of resources
saved without legacy details.
Each revision returns its saved JSON, whiteout deletion details, and what
the current validator finds in it. When the validator reads the
document, `root` describes it by meaning, whatever keys spell its
properties: the relations and recipients of the root and of every
document it embeds, with the resource currently registered under each
IRI, and its custom extension properties. Each revision is read by
evidence of its own: local revisions by anyone, revisions addressed to the
public by anyone, and received revisions by members of the instance that
received them. `DocumentNode.source` tells which revision an embedded
document came from, whether it keeps that revision's contents or was
derived from it, and whether that revision is still current, superseded, or
deleted; it is null when the viewer may not read that revision, and the
embedded document itself stays readable. Deleting a resource or its
author hides none of its revisions by itself. A `Resource` is returned by
`node`, `Activity.object`, and relations and recipients whenever the
viewer may read one of its revisions, even after its current state was
restricted, while `Resource.detail` and the typed node stay hidden.
`Actor.objects` takes a `filter` whose `includeDeleted` lists deleted
objects too, and `Object.deleted` tells when one was deleted. [[#154]]
- Fixed `Resource.detail` to return `null` without a field error when the
resource has no corresponding detail record.
[[#150], [#164] by Hong Minhee\]

[#154]: https://github.com/fedify-dev/drfed/issues/154

### JavaScript/TypeScript APIs

- Added `@drfed/federation/local-write`, the common write operations for
Expand Down Expand Up @@ -85,6 +110,13 @@ To be released.
revision ID is stale, and object histories can end with a whiteout deletion
marker.
[[#150], [#164] by Hong Minhee\]
- Added the `@drfed/federation/document` subpath. Its
`interpretDocument()` returns every vocabulary document of a saved
document with its relations, recipients, and custom extension
properties, read by meaning as the validator reads them. [[#154]]
- Added `extensionProperties` to the nodes `describeDocument()` in
`@drfed/models/document` returns: the source keys of each document's
custom extension properties. [[#154]]
- Added the `@drfed/federation/serving` subpath. It exports
`publicDocument()`, the serialization federation reads use for saved
documents, `parseVocab()`, which parses such a document into a Fedify
Expand Down Expand Up @@ -116,6 +148,17 @@ To be released.
poll-specific rules remain separate work. The supported properties and
representation limits are documented in *packages/models/README.md*.
[[#151], [#166] by Jiwon Kwon\]
- `appendResourceRevision()` and `writeTypedResourceRevision()` in
`@drfed/models/resource-revision` accept `embeddings`, which record the
revision each embedded document came from and whether it keeps that
revision's contents or was derived from it. `commitLocalWrite()` in
`@drfed/federation/local-write` records them for every document it saves,
and `create` and `edit` requests accept `sources` to declare the revision
an embedded document was loaded from. Declaring sources requires the
`unreadableRevisions` option of `previewLocalWrite()` and
`commitLocalWrite()`, such as `unreadableRevisions()` of the new
`@drfed/graphql/readable`; a source that is missing or that the member
may not read fails alike with `source_unavailable`. [[#154]]

[#151]: https://github.com/fedify-dev/drfed/issues/151
[#152]: https://github.com/fedify-dev/drfed/issues/152
Expand Down
8 changes: 8 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -715,6 +715,14 @@ The GraphQL types for activity deliveries live in
*src/activity-delivery/entry.ts*. Delivery contents are private to local
instance members and administrators, including Relay node lookups.

The GraphQL types for resource revisions live in *src/revision.ts*. Each
revision is read by evidence of its own, through `readableRevision()` in
*src/readable.ts*, never by the current state of its resource nor by where
its embedded documents came from; only `DocumentNode.source` checks a source
revision. Filter revisions by it before paging, and use
`unreadableRevisions()` wherever another layer, such as a local write's
`sources`, must apply the same rule.


CLI and server changes
----------------------
Expand Down
27 changes: 27 additions & 0 deletions changes.d/graphql/resource-revisions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
links:
'#154': https://github.com/fedify-dev/drfed/issues/154
---
- Added `Resource.currentRevision`, `Resource.revisions`, newest first,
`Resource.revision(sequence:)`, and the `ResourceRevision` node, which
return the saved revisions of a resource, including those of resources
saved without legacy details.
Each revision returns its saved JSON, whiteout deletion details, and what
the current validator finds in it. When the validator reads the
document, `root` describes it by meaning, whatever keys spell its
properties: the relations and recipients of the root and of every
document it embeds, with the resource currently registered under each
IRI, and its custom extension properties. Each revision is read by
evidence of its own: local revisions by anyone, revisions addressed to the
public by anyone, and received revisions by members of the instance that
received them. `DocumentNode.source` tells which revision an embedded
document came from, whether it keeps that revision's contents or was
derived from it, and whether that revision is still current, superseded, or
deleted; it is null when the viewer may not read that revision, and the
embedded document itself stays readable. Deleting a resource or its
author hides none of its revisions by itself. A `Resource` is returned by
`node`, `Activity.object`, and relations and recipients whenever the
viewer may read one of its revisions, even after its current state was
restricted, while `Resource.detail` and the typed node stay hidden.
`Actor.objects` takes a `filter` whose `includeDeleted` lists deleted
objects too, and `Object.deleted` tells when one was deleted. [[#154]]
12 changes: 12 additions & 0 deletions changes.d/javascript/document-interpretation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
links:
'#154': https://github.com/fedify-dev/drfed/issues/154
---
- Added the `@drfed/federation/document` subpath. Its
`interpretDocument()` returns every vocabulary document of a saved
document with its relations, recipients, and custom extension
properties, read by meaning as the validator reads them. [[#154]]

- Added `extensionProperties` to the nodes `describeDocument()` in
`@drfed/models/document` returns: the source keys of each document's
custom extension properties. [[#154]]
15 changes: 15 additions & 0 deletions changes.d/javascript/embedded-sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
links:
'#154': https://github.com/fedify-dev/drfed/issues/154
---
- `appendResourceRevision()` and `writeTypedResourceRevision()` in
`@drfed/models/resource-revision` accept `embeddings`, which record the
revision each embedded document came from and whether it keeps that
revision's contents or was derived from it. `commitLocalWrite()` in
`@drfed/federation/local-write` records them for every document it saves,
and `create` and `edit` requests accept `sources` to declare the revision
an embedded document was loaded from. Declaring sources requires the
`unreadableRevisions` option of `previewLocalWrite()` and
`commitLocalWrite()`, such as `unreadableRevisions()` of the new
`@drfed/graphql/readable`; a source that is missing or that the member
may not read fails alike with `source_unavailable`. [[#154]]
105 changes: 90 additions & 15 deletions docs/internals/local-writes.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,16 +82,17 @@ after the first write throw out of the transaction; nothing partial is left. A
replayed token finds its resources already saved (`resource_conflict`) or the
object already changed (`revision_conflict`).

| Error | Meaning |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| `invalid_request` | Malformed request or resource descriptors, or a missing token or reservation. |
| `invalid_document` | Validator, authority or server-owned-field diagnostics at submitted paths. |
| `actor_not_found` | The actor is missing, deleted, not local, on an expired instance, or not the member's. |
| `invalid_instance_host` | The stored instance host cannot be parsed by this server. |
| `stale_preview` | The token is invalid, expired, or for another account or request. |
| `revision_conflict` | The object's current revision is not the expected one. |
| `resource_conflict` | The resources were already saved, or an IRI is another kind of resource. |
| `unsupported_edit` | The object is deleted, not the actor's, changes type, or cannot be kept in step (see below). |
| Error | Meaning |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `invalid_request` | Malformed request or resource descriptors, or a missing token or reservation. |
| `invalid_document` | Validator, authority or server-owned-field diagnostics at submitted paths. |
| `actor_not_found` | The actor is missing, deleted, not local, on an expired instance, or not the member's. |
| `invalid_instance_host` | The stored instance host cannot be parsed by this server. |
| `stale_preview` | The token is invalid, expired, or for another account or request. |
| `revision_conflict` | The object's current revision is not the expected one. |
| `resource_conflict` | The resources were already saved, or an IRI is another kind of resource. |
| `unsupported_edit` | The object is deleted, not the actor's, changes type, or cannot be kept in step (see below). |
| `source_unavailable` | A declared source is missing, not a snapshot of its document, or one the member may not read. |


Identity and documents
Expand Down Expand Up @@ -136,9 +137,80 @@ from its semantic `to`, `cc`, `bto`, `bcc` and `audience`, each value at its
source position: IRIs as resolved, embedded documents by `id`, `Link` values by
`href`, also written as a list of one value, and anonymous values without a row.
Relations index `actor`, `object`, `target`, `origin`, `result`, `instrument`
and `attributedTo`. A document that spells one of these properties in several
ways is refused, since its index would otherwise leave occurrences out. Indexes
stay `partial`; the documents remain authoritative.
and `attributedTo`. Both indexes come from `interpretDocument()` in
`@drfed/federation/document`, which GraphQL reads use too. A document that
spells one of these properties in several ways is refused, since its index
would otherwise leave occurrences out. Indexes stay `partial`; the documents
remain authoritative.


Embedded document sources
-------------------------

Every saved document records, for each embedded document with an `id`, the
revision it came from when the server knows it, as
[resource revisions](resource-revisions.md#embedded-document-sources)
describe. `Link` values and anonymous documents get no source. The source is
found in this order:

1. A resource saved earlier in the same write, such as a nested new resource
kept embedded or the version an edit's `Update` embeds. When the
embedded document keeps that resource's new revision, the documents it
embeds take the sources recorded for that revision at their own paths,
so an `Update` records the sources of the version it carries.

2. A source the request declares for the embedded document's submitted path:

~~~~ ts
const request = {
operation: "create",
actorId,
document: { type: "Like", object: changedNote },
resources: [{ path: [], kind: "activity" }],
sources: [{ path: ["object"], revisionId: loadedRevisionId }],
} as const;
~~~~

An editor declares the revision it loaded a document from, so that a
changed copy keeps its source. Both `create` and `edit` accept `sources`,
and the preview token binds them. Each path must name an embedded document
with an `id` that is not a new resource of the write; otherwise the
request is `invalid_request`. Its revision must be a snapshot of the
resource registered under that `id` that the member may read; otherwise
the write fails with `source_unavailable`, with a diagnostic at the
declared path. A missing revision and one the member may not read fail
alike, so the error tells nothing of revisions the member may not read.

The local write operations do not decide who may read a revision. The
caller passes `unreadableRevisions(ids)` in the options of both
`previewLocalWrite()` and `commitLocalWrite()`, which check the declared
revisions again, since the member's access may change after the
preview. GraphQL's rule is `unreadableRevisions(viewer, ids)` in
`@drfed/graphql/readable`:

~~~~ ts
const access = {
unreadableRevisions: (ids: readonly Uuid[]) =>
unreadableRevisions({ db, account }, ids),
};
await previewLocalWrite(env, principal, request, access);
~~~~

A request that declares sources without the check is `invalid_request`.

Any other embedded document has an unknown source, even when it equals a
stored revision of the resource under its `id`: the server never guesses a
source from an IRI. A pasted document and a loaded one declared as its
source therefore differ only in `DocumentNode.source`.

An embedded document is a `snapshot` of its source when its effective context
equals the source document's and its JSON, apart from the `@context` key,
equals the source document's, whatever the order of object keys. Otherwise it
is `derived`. The comparison is strict, so a document only re-serialized
differently reads as derived, never the reverse. Previews and commit results
do not report sources: a writer could otherwise learn whether a guessed
document equals a revision they may not read. Writes through
`createLegacyObject()` record no sources.


Edits and deletions
Expand All @@ -156,8 +228,11 @@ A deletion appends a whiteout and keeps the object's current addressing, which
describes the last content. The generated `Delete` refers to the object by IRI
and copies the last version's addressing under its context.

Resources created by the common write have revisions only, so GraphQL details
ignore them until #154; federation reads serve their documents. Objects created
Resources created by the common write have revisions only, so GraphQL
`Resource.detail` ignores them; `Resource.currentRevision` and
`Resource.revisions` read them, as [resource
revisions](resource-revisions.md#graphql-reads) describe, and federation reads
serve their documents. Objects created
by the `createObject` mutation also have legacy typed rows that serving reads;
`writeTypedResourceRevision()` keeps those rows in step. Before writing, the
served columns must agree with the current revision, or the object is refused
Expand Down
Loading
Loading