@graffiti-garden/api 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graffiti-garden/api",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "The heart of Graffiti",
   "types": "./dist/src/index.d.ts",
   "module": "./dist/index.mjs",
@@ -48,11 +48,11 @@
   },
   "homepage": "https://api.graffiti.garden/classes/Graffiti.html",
   "devDependencies": {
-    "@types/node": "^22.13.4",
-    "tsx": "^4.19.2",
-    "typedoc": "^0.27.7",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
+    "@types/node": "^24.7.2",
+    "tsx": "^4.20.6",
+    "typedoc": "^0.28.14",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   },
   "dependencies": {
     "fast-json-patch": "^3.1.1",

package/src/1-api.ts

@@ -14,171 +14,90 @@ import type { JSONSchema } from "json-schema-to-ts";
 
 /**
  * This API describes a small but powerful set of methods that
- * can be used to create many different kinds of social media applications,
- * all of which can interoperate.
- * These methods should satisfy all of an application's needs for
+ * can be used to create many different kinds of social applications,
+ * from applications like Twitter, to Messenger, to Wikipedia, to many more new designs.
+ * See the [Graffiti project website](https://graffiti.garden)
+ * for links to example applications. Additionally, apps built on top
+ * of the API interoperate with each other so you can seamlessly switch
+ * between apps without losing your friends or data.
+ *
+ * These API methods should satisfy all of an application's needs for
  * the communication, storage, and access management of social data.
  * The rest of the application can be built with standard client-side
- * user interface tools to present and interact with the data —
- * no server code necessary.
- * The Typescript source for this API is available at
- * [graffiti-garden/api](https://github.com/graffiti-garden/api).
+ * user interface tools to present and interact with that data—no server code necessary!
+ *
+ * The Typescript code for this API is [open source on Github](https://github.com/graffiti-garden/api).
  *
  * There are several different implementations of this Graffiti API available,
- * including a [federated implementation](https://github.com/graffiti-garden/implementation-federated),
- * that lets users choose where their data is stored,
+ * including a [federated implementation](https://github.com/graffiti-garden/implementation-remote),
+ * that lets people choose where their data is stored (you do not need to host your own server)
  * and a [local implementation](https://github.com/graffiti-garden/implementation-local)
- * that can be used for testing and development. In our design of Graffiti, this API is our
- * primary focus as it is the layer that shapes the experience
- * of developing applications. While different implementations can provide tradeoffs between
- * other important properties (e.g. privacy, security, scalability), those properties
- * are useless if the system as a whole doesn't expose useful functionality to developers.
- *
- * On the other side of the stack, there is [Vue plugin](https://github.com/graffiti-garden/wrapper-vue/)
- * that wraps around this API to provide reactivity. Other high-level libraries
- * will be available in the future.
- *
- * ## Overview
- *
- * Graffiti provides applications with methods to create and store data
- * on behalf of their users using standard CRUD operations:
- *  {@link put}, {@link get}, {@link patch}, and {@link delete}.
- * This data can represent both social artifacts (e.g. posts, profiles) and
- * activities (e.g. likes, follows) and is stored as JSON.
- *
- * The social aspect of Graffiti comes from the {@link discover} method
- * which allows applications to find objects that other users made.
- * It is a lot like a traditional query operation, but it only
- * returns objects that have been placed in particular
- * {@link GraffitiObjectBase.channels | `channels`}
- * specified by the discovering application.
+ * that can be used for testing and development. Different implementations can
+ * be swapped-in in the future without changing the API or any of the apps built on
+ * top of it. In fact, we're working on an end-to-end encrypted version now!
+ * [Follow Theia on BlueSky for updates](https://bsky.app/profile/theias.place).
  *
- * Graffiti builds on well known concepts and standards wherever possible.
- * JSON Objects can be typed with [JSON Schema](https://json-schema.org/) and patches
- * can be applied with [JSON Patch](https://jsonpatch.com).
- * For interoperability between Graffiti applications, we recommend that
- * objects use established properties from the
- * [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/) when available,
- * however it is always possible to create additional properties, contributing
- * to the broader [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).
+ * On the other side of the stack, there is [Vue plugin](https://vue.graffiti.garden/variables/GraffitiPlugin.html)
+ * that wraps around this API to provide reactivity. Other plugin frameworks
+ * and high-level libraries will be available in the future.
  *
- * {@link GraffitiObjectBase.channels | `channels`} are one of the major concepts
- * unique to Graffiti along with *interaction relativity*, defined below.
- * Channels create boundaries between public spaces and work to prevent
- * [context collapse](https://en.wikipedia.org/wiki/Context_collapse)
- * even in a highly interoperable environment.
- * Interaction relativity means that all interactions between users are
- * actually atomic single-user operations that can be interpreted in different ways,
- * which also supports interoperability and pluralism.
+ * ## API Overview
  *
- * ### Channels
+ * The Graffiti API provides applications with methods for {@link login} and {@link logout},
+ * methods to store data objects using standard database operations ({@link put}, {@link get}, {@link patch}, and {@link delete}),
+ * and a method to {@link discover} data objects from other people.
+ * These data objects have a couple structured properties:
+ * - {@link GraffitiObjectBase.url | `url`} (string): A globally unique identifier and locator for the object.
+ * - {@link GraffitiObjectBase.actor | `actor`} (string): An unforgeable identifier for the creator of the object.
+ * - {@link GraffitiObjectBase.allowed | `allowed`} (string[] | undefined): An array of the identities who are allowed to access the object (undefined for public objects).
+ * - {@link GraffitiObjectBase.channels | `channels`} (string[]): An array of the *contexts* in which the object should appear.
+ * - {@link GraffitiObjectBase.lastModified | `revision`} (number): A number to compare different versions of an object.
  *
- * {@link GraffitiObjectBase.channels | `channels`}
- * are a way for the creators of social data to express the intended audience of their
- * data. When a user creates data using the {@link put} method, they
- * can place their data in one or more channels.
- * Content consumers using the {@link discover} method will only see data
- * contained in one of the channels they specify.
- *
- * While many channels may be public, they partition
- * the public into different "contexts", mitigating the
- * phenomenon of [context collapse](https://en.wikipedia.org/wiki/Context_collapse) or the "flattening of multiple audiences."
- * Any [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) can be used as a channel, and so channels can represent people,
- * comment threads, topics, places (real or virtual), pieces of media, and more.
- *
- * For example, consider a comment on a post. If we place that comment in the channel
- * represented by the post's URL, then only people viewing the post will know to
- * look in that channel, giving it visibility akin to a comment on a blog post
- * or comment on Instagram ([since 2019](https://www.buzzfeednews.com/article/katienotopoulos/instagrams-following-activity-tab-is-going-away)).
- * If we also place the comment in the channel represented by the commenter's URI (their
- * {@link GraffitiObjectBase.actor | `actor` URI}), then people viewing the commenter's profile
- * will also see the comment, giving it more visibility, like a reply on Twitter.
- * If we *only* place the comment in the channel represented by the commenter's URI, then
- * it becomes like a quote tweet ([prior to 2020](https://x.com/Support/status/1300555325750292480)),
- * where the comment is only visible to the commenter's followers but not the audience
- * of the original post.
- *
- * The channel model differs from other models of communication such as the
- * [actor model](https://www.w3.org/TR/activitypub/#Overview) used by ActivityPub,
- * the protocol underlying Mastodon, or the [firehose model](https://bsky.social/about/blog/5-5-2023-federation-architecture)
- * used by the AT Protocol, the protocol underlying BlueSky.
- * The actor model is a fusion of direct messaging (like Email) and broadcasting
- * (like RSS) and works well for follow-based communication but struggles
- * to pass information via other rendez-vous.
- * In the actor model, even something as simple as comments can be
- * [very tricky and require server "side effects"](https://seb.jambor.dev/posts/understanding-activitypub-part-3-the-state-of-mastodon/).
- * The firehose model dumps all user data into one public database,
- * which doesn't allow for the carving out of different contexts that we did in our comment
- * example above. In the firehose model a comment will always be visible to *both* the original post's audience and
- * the commenter's followers.
- *
- * In some sense, channels provide a sort of "social access control" by forming
- * expectations about the audiences of different online spaces.
- * As a real world analogy, oftentimes support groups, such as alcoholics
- * anonymous, are open to the public but people in those spaces feel comfortable sharing intimate details
- * because they have expectations about the other people attending.
- * If someone malicious went to support groups just to spread people's secrets,
- * they would be shamed for violating these norms.
- * Similarly, in Graffiti, while you could spider public channels like a search engine
- * to find content about a person, revealing that you've done such a thing
- * would be shameful.
+ * All other data is stored in the object's unstructured {@link GraffitiObjectBase.value | `value`} property.
+ * This data can be used to represent social artifacts (e.g. posts, profiles) and activities (e.g. likes, follows).
+ * For example, a post might have the value:
+
+ * ```js
+ * {
+ *   title: "My First Post",
+ *   content: "Hello, world!",
+ *   published: 1630483200000
+ * }
+ * ```
  *
- * Still, social access control is not perfect and so in situations where privacy is important,
- * objects can also be given
- * an {@link GraffitiObjectBase.allowed | `allowed`} list.
- * For example, to send someone a direct message you should put an object representing
- * that message in the channel that represents them (their {@link GraffitiObjectBase.actor | `actor` URI}),
- * so they can find it, *and* set the `allowed` field to only include the recipient,
- * so only they can read it.
+ * a profile might have the value:
  *
- * ### Interaction relativity
+ * ```js
+ * {
+ *   name: "Theia Henderson",
+ *   pronouns: "she/her",
+ *   describes: "did:web:theias.place" // Theia's actor ID
+ * }
+ * ```
  *
- * Interaction relativity posits that "interaction between two individuals only
- * exists relative to an observer," or equivalently, all interaction is [reified](https://en.wikipedia.org/wiki/Reification_(computer_science)).
- * For example, if one user creates a post and another user wants to "like" that post,
- * their like is not modifying the original post, it is simply another data object that points
- * to the post being liked, via its {@link GraffitiObjectBase.url | URL}.
+ * and a "Like" might have the value:
  *
- * ```json
+ * ```js
  * {
- *   activity: 'like',
- *   target: 'url-of-the-post-i-like',
- *   actor: 'my-user-id'
+ *   activity: "Like",
+ *   target: "graffiti:remote:pod.graffiti.garden/12345" // The URL of the graffiti object being liked
  * }
  * ```
  *
- * In Graffiti, all interactions including *moderation* and *collaboration* are relative.
- * This means that applications can freely choose which interactions
- * they want to express to their users and how.
- * For example, one application could have a single fixed moderator,
- * another could allow users to choose which moderators they would like filter their content
- * like [Bluesky's stackable moderation](https://bsky.social/about/blog/03-12-2024-stackable-moderation),
- * and another could implement a fully democratic system like [PolicyKit](https://policykit.org/).
- * Each of these applications is one interpretation of the underlying refieid user interactions and
- * users can freely switch between them.
+ * New social artifacts and activities can be easily created, simply
+ * by creating new objects with appropriate properties. Despite the lack of
+ * structure, we expect Graffiti object properties to adhere to a "[folksonomy](https://en.wikipedia.org/wiki/Folksonomy)",
+ * similar to hashtags. Any string can be used as a hashtag on Twitter,
+ * but there is social value in using the same hashtags at other people and
+ * so a structure naturally emerges. Similarly, Graffiti objects
+ * can have arbitrary properties but if people use the same properties as each other,
+ * their apps will interoperate, which has social value.
  *
- * Interaction relativy also allows applications to introduce new sorts of interactions
- * without having to coordinate with all the other existing applications,
- * keeping the ecosystem flexible and interoperable.
- * For example, an application could [add a "Trust" button to posts](https://social.cs.washington.edu/pub_details.html?id=trustnet)
- * and use it assess the truthfulness of posts made on applications across Graffiti.
- * New sorts of interactions like these can be smoothly absorbed by the broader ecosystem
- * as a [folksonomy](https://en.wikipedia.org/wiki/Folksonomy).
- *
- * Interactivy relativity is realized in Graffiti through two design decisions:
- * 1. The creators of objects can only modify their own objects. It is important for
- *    users to be able to change and delete their own content to respect their
- *    [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten),
- *    but beyond self-correction and self-censorship all other interaction is reified.
- *    Many interactions can be reified via pointers, as in the "like" example above, and collaborative
- *    edits can be refieid via [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type).
- * 2. No one owns channels. Unlike IRC/Slack channels or [Matrix rooms](https://matrix.org/docs/matrix-concepts/rooms_and_events/),
- *    anyone can post to any channel, so long as they know the URI of that channel.
- *    It is up to applications to hide content from channels either according to manual
- *    filters or in response to user action.
- *    For example, a user may create a post with the flag `disableReplies`.
- *    Applications could then filter out any content from the replies channel
- *    that the original poster has not specifically approved.
+ * For a more complete and detailed overview of Graffiti's design, please
+ * refer to [this section of the Graffiti paper](https://dl.acm.org/doi/10.1145/3746059.3747627#sec-3),
+ * published in ACM UIST 2025. The paper also overviews {@link GraffitiObjectBase.channels | `channels`},
+ * which are Graffiti's means of organizing data contextually, and a concept called "total reification",
+ * which handles explains how moderation, collaboration, and other interactions are managed.
  *
  * @groupDescription CRUD Methods
  * Methods for {@link put | creating}, {@link get | reading}, {@link patch | updating},
@@ -186,7 +105,7 @@ import type { JSONSchema } from "json-schema-to-ts";
  * @groupDescription Query Methods
  * Methods that retrieve or accumulate information about multiple {@link GraffitiObjectBase | Graffiti objects} at a time.
  * @groupDescription Session Management
- * Methods and properties for logging in and out of a Graffiti implementation.
+ * Methods and properties for logging in and out.
  */
 export abstract class Graffiti {
   /**
@@ -204,7 +123,7 @@ export abstract class Graffiti {
    * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
    * is not the same `actor` as the one who created the object.
    *
-   * @returns The object that was replaced if one one exists, otherwise an object with
+   * @returns Returns the object that was replaced if one one exists, otherwise returns an object with
    * with an empty {@link GraffitiObjectBase.value | `value`},
    * {@link GraffitiObjectBase.channels | `channels`}, and {@link GraffitiObjectBase.allowed | `allowed`}
    * list.
@@ -217,7 +136,7 @@ export abstract class Graffiti {
     /**
      * The object to be put. This object is statically type-checked against the [JSON schema](https://json-schema.org/) that can be optionally provided
      * as the generic type parameter. We highly recommend providing a schema to
-     * ensure that the PUT object matches subsequent {@link get} or {@link discover}
+     * ensure that the put object matches subsequent {@link get} or {@link discover}
      * methods.
      */
     object: GraffitiPutObject<Schema>,
@@ -238,9 +157,11 @@ export abstract class Graffiti {
    * the object's `actor`,
    * the object's {@link GraffitiObjectBase.allowed | `allowed`} and
    * {@link GraffitiObjectBase.channels | `channels`} properties are
-   * not revealed, similar to a BCC.
+   * not revealed, similar to a BCC email.
+   *
+   * @returns Returns the retrieved object.
    *
-   * @throws {@link GraffitiErrorNotFound} if the object does not exist, has been deleted, or the user is not
+   * @throws {@link GraffitiErrorNotFound} if the object does not exist, has been deleted, or the actor is not
    * {@link GraffitiObjectBase.allowed | `allowed`} to access it.
    *
    * @throws {@link GraffitiErrorSchemaMismatch} if the retrieved object does not match the provided schema.
@@ -270,12 +191,12 @@ export abstract class Graffiti {
    * The patching {@link GraffitiObjectBase.actor | `actor`} must be the same as the
    * `actor` that created the object.
    *
-   * @returns The original object prior to the patch with its
+   * @returns Returns the original object prior to the patch with its
    * {@link GraffitiObjectBase.lastModified | `lastModified`}
-   * property updated to the time of deletion.
+   * property updated to the time of patching.
    *
    * @throws {@link GraffitiErrorNotFound} if the object does not exist, has already been deleted,
-   * or the user is not {@link GraffitiObjectBase.allowed | `allowed`} to access it.
+   * or the actor is not {@link GraffitiObjectBase.allowed | `allowed`} to access it.
    *
    * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
    * is not the same `actor` as the one who created the object.
@@ -305,17 +226,17 @@ export abstract class Graffiti {
    * `actor` that created the object.
    *
    * It is not possible to re-{@link put} an object that has been deleted
-   * to ensure a user's [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten).
+   * to ensure a person's [right to be forgotten](https://en.wikipedia.org/wiki/Right_to_be_forgotten).
    * In cases where deleting and restoring an object is useful, an object's
    * {@link GraffitiObjectBase.allowed | `allowed`} property can be set to
-   * an empty list to hide it from all users except the creator.
+   * an empty list to hide it from all actors except the creator.
    *
-   * @returns The object that was deleted with its
+   * @returns Returns the object that was deleted with its
    * {@link GraffitiObjectBase.lastModified | `lastModified`}
    * property updated to the time of deletion.
    *
    * @throws {@link GraffitiErrorNotFound} if the object does not exist,  has already been deleted,
-   * or the user is not {@link GraffitiObjectBase.allowed | `allowed`} to access it.
+   * or the actor is not {@link GraffitiObjectBase.allowed | `allowed`} to access it.
    *
    * @throws {@link GraffitiErrorForbidden} if the {@link GraffitiObjectBase.actor | `actor`}
    * is not the same `actor` as the one who created the object.
@@ -335,7 +256,7 @@ export abstract class Graffiti {
   ): Promise<GraffitiObjectBase>;
 
   /**
-   * Discovers objects created by any user that are contained
+   * Discovers objects created by any actor that are contained
    * in at least one of the given {@link GraffitiObjectBase.channels | `channels`}
    * and match the given [JSON Schema](https://json-schema.org).
    *
@@ -364,7 +285,7 @@ export abstract class Graffiti {
    * {@link GraffitiObjectBase.lastModified | `lastModified`} fields must be used
    * to determine which object is the most recent.
    *
-   * @returns A stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
+   * @returns Returns a stream of objects that match the given {@link GraffitiObjectBase.channels | `channels`}
    * and [JSON Schema](https://json-schema.org).
    *
    * @group Query Methods
@@ -392,18 +313,18 @@ export abstract class Graffiti {
    * {@link GraffitiObjectBase.channels | `channels`}
    * that were created by the querying {@link GraffitiObjectBase.actor | `actor`}
    * and match the given [JSON Schema](https://json-schema.org).
-   * Unlike {@link discover}, this method will not return objects created by other users.
+   * Unlike {@link discover}, this method will not return objects created by other actors.
    *
-   * This method is not useful for most applications, but necessary for
-   * getting a global view of all a user's Graffiti data or debugging
-   * channel usage.
+   * Like {@link channelStats}, this method is not useful for most applications,
+   * but necessary for getting a global view of all an actor's Graffiti data
+   * to implement something like Facebook's Activity Log or a debugging interface.
    *
    * Like {@link discover}, objects are returned asynchronously as they are discovered,
    * the stream will end once all leads have been exhausted, and the stream
    * can be continued using the {@link GraffitiObjectStreamReturn.continue | `continue`}
    * method or {@link GraffitiObjectStreamReturn.cursor | `cursor`} string.
    *
-   * @returns A stream of objects created by the querying {@link GraffitiObjectBase.actor | `actor`}
+   * @returns Returns a stream of objects created by the querying {@link GraffitiObjectBase.actor | `actor`}
    * that do not belong to any {@link GraffitiObjectBase.channels | `channels`}
    * and match the given [JSON Schema](https://json-schema.org).
    *
@@ -424,17 +345,18 @@ export abstract class Graffiti {
   /**
    * Returns statistics about all the {@link GraffitiObjectBase.channels | `channels`}
    * that an {@link GraffitiObjectBase.actor | `actor`} has posted to.
-   * This is not very useful for most applications, but
-   * necessary for certain applications where a user wants a
-   * global view of all their Graffiti data or to debug
-   * channel usage.
+   * This method will not return statistics related to any other actor's channel usage.
    *
-   * Like {@link discover}, objects are returned asynchronously as they are discovered,
+   * Like {@link recoverOrphans}, this method is not useful for most applications,
+   * but necessary for getting a global view of all an actor's Graffiti data
+   * to implement something like Facebook's Activity Log or a debugging interface.
+   *
+   * Like {@link discover}, objects are returned asynchronously as they are discovered and
    * the stream will end once all leads have been exhausted.
    *
    * @group Query Methods
    *
-   * @returns A stream of statistics for each {@link GraffitiObjectBase.channels | `channel`}
+   * @returns Returns a stream of statistics for each {@link GraffitiObjectBase.channels | `channel`}
    * that the {@link GraffitiObjectBase.actor | `actor`} has posted to.
    */
   abstract channelStats(
@@ -479,8 +401,9 @@ export abstract class Graffiti {
 
   /**
    * Begins the login process. Depending on the implementation, this may
-   * involve redirecting the user to a login page or opening a popup,
-   * so it should always be called in response to a user action.
+   * involve redirecting to a login page or opening a popup,
+   * so it should always be called in response to a gesture, such as clicking
+   * a button, due to the [feature-gating browser security feature](https://developer.mozilla.org/en-US/docs/Web/Security/User_activation).
    *
    * The {@link GraffitiSession | session} object is returned
    * asynchronously via {@link Graffiti.sessionEvents | sessionEvents}
@@ -521,9 +444,10 @@ export abstract class Graffiti {
   ): Promise<void>;
 
   /**
-   * Begins the logout process. Depending on the implementation, this may
+   * Begins the logout process for a particular {@link GraffitiSession | session}. Depending on the implementation, this may
    * involve redirecting the user to a logout page or opening a popup,
-   * so it should always be called in response to a user action.
+   * so it should always be called in response to a gesture, such as clicking
+   * a button, due to the [feature-gating browser security feature](https://developer.mozilla.org/en-US/docs/Web/Security/User_activation).
    *
    * A confirmation will be returned asynchronously via
    * {@link Graffiti.sessionEvents | sessionEvents}
@@ -540,7 +464,7 @@ export abstract class Graffiti {
 
   /**
    * An event target that can be used to listen for the following
-   * events and they're corresponding event types:
+   * events and their corresponding event types:
    * - `login` - {@link GraffitiLoginEvent}
    * - `logout` - {@link GraffitiLogoutEvent}
    * - `initialized` - {@link GraffitiSessionInitializedEvent}

package/src/2-types.ts

@@ -34,8 +34,8 @@ export interface GraffitiObjectBase {
    * {@link Graffiti.discover} method. This allows creators to express the intended audience of their object
    * which helps to prevent [context collapse](https://en.wikipedia.org/wiki/Context_collapse) even
    * in the highly interoperable ecosystem that Graffiti envisions. For example, channel URIs may be:
-   * - A user's own {@link actor | `actor`} URI. Putting an object in this channel is a way to broadcast
-   * the object to the user's followers, like posting a tweet.
+   * - A actor's own {@link actor | `actor`} URI. Putting an object in this channel is a way to broadcast
+   * the object to the actor's followers, like posting a tweet.
    * - The URL of a Graffiti post. Putting an object in this channel is a way to broadcast to anyone viewing
    * the post, like commenting on a tweet.
    * - A URI representing a topic. Putting an object in this channel is a way to broadcast to anyone interested
@@ -49,8 +49,8 @@ export interface GraffitiObjectBase {
    * also know the right {@link channels | `channel` } to look in). An object can always be accessed by its creator, even if
    * the `allowed` array is empty.
    *
-   * The `allowed` array is not revealed to users other than the creator, like
-   * a BCC email. A user may choose to add a `to` property to the object's {@link value | `value`} to indicate
+   * The `allowed` array is not revealed to actors other than the creator, like
+   * a BCC email. An actor may choose to add a `to` property to the object's {@link value | `value`} to indicate
    * other recipients, however this is not enforced by Graffiti and may not accurately reflect the actual `allowed` array.
    *
    * `allowed` can be combined with {@link channels | `channels`}. For example, to send someone a direct message
@@ -87,23 +87,28 @@ export interface GraffitiObjectBase {
    * to pull from multiple coexisting Graffiti implementations without collision.
    * Existing schemes include `graffiti:local:` for objects stored locally
    * (see the [local implementation](https://github.com/graffiti-garden/implementation-local))
-   * and `graffiti:remote:` for objects stored on Graffiti-specific web servers (see the
-   * [remote implementation](https://github.com/graffiti-garden/implementation-remote)).
+   * and `graffiti:remote:` for objects stored on Graffiti-specific web servers (see the [remote implementation](https://github.com/graffiti-garden/implementation-remote))
    * Options available in the future might include `graffiti:solid:` for objects stored on Solid servers
    * or `graffiti:p2p:` for objects stored on a peer-to-peer network.
    */
   url: string;
 
   /**
-   * The time the object was last modified, measured in milliseconds since January 1, 1970.
-   * It can be used to compare object versions.
-   * A number, rather than an ISO string or Date object, is used for easy comparison, sorting,
-   * and JSON Schema [range queries](https://json-schema.org/understanding-json-schema/reference/numeric#range).
+   * A number used to compare different versions of an object that has been
+   * updated via replacement (see {@link Graffiti.put}) or
+   * patch (see {@link Graffiti.patch}). Newer versions of
+   * an object have larger `revision` values than older versions.
+   * The `revision` can only
+   * be used to compare different versions of the same object,
+   * but cannot reliably be used to compare different objects.
+   * In cases where comparing different objects by time is useful,
+   * you could instead add `createdAt` or `lastModified` timestamp properties
+   * to an object's {@link value | `value`}.
    *
-   * It is possible to use this value to sort objects in a user's interface but in many cases it would be better to
-   * use a [`published`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-published)
-   * property in the object's {@link value | `value`} to indicate when the object was created
-   * rather than when it was modified.
+   * Depending on the implementation, the revision may be a timestamp,
+   * an incremental counter, may include randomness for obfuscation, and so on.
+   * Be careful not to rely on any of these specific `revision` instantiations
+   * as they may not be consistent across different implementations.
    */
   lastModified: number;
 }
@@ -141,14 +146,14 @@ export const GraffitiObjectJSONSchema = {
 /**
  * This is an object containing only the {@link GraffitiObjectBase.url | `url`}
  * property of a {@link GraffitiObjectBase | GraffitiObject}.
- * It is used as a utility type so that users can call {@link Graffiti.get},
+ * It is used as a utility type so that applications can call {@link Graffiti.get},
  * {@link Graffiti.patch}, or {@link Graffiti.delete} directly on an object
  * rather than on `object.url`.
  */
 export type GraffitiObjectUrl = Pick<GraffitiObjectBase, "url">;
 
 /**
- * This object is a subset of {@link GraffitiObjectBase} that a user must construct locally before calling {@link Graffiti.put}.
+ * This object is a subset of {@link GraffitiObjectBase} that must be constructed locally before calling {@link Graffiti.put}.
  * This local copy does not require system-generated properties and may be statically typed with
  * a [JSON schema](https://json-schema.org/) to prevent the accidental creation of erroneous objects.
  *
@@ -180,13 +185,12 @@ export const GraffitiPutObjectJSONSchema = {
 
 /**
  * This object contains information that the underlying implementation can
- * use to verify that a user has permission to operate a
- * particular {@link GraffitiObjectBase.actor | `actor`}.
+ * use to authenticate a particular {@link GraffitiObjectBase.actor | `actor`}.
  * This object is required of all {@link Graffiti} methods
  * that modify objects and is optional for methods that read objects.
  *
  * At a minimum the `session` object must contain the
- * {@link GraffitiSession.actor | `actor`} URI the user wants to authenticate with.
+ * {@link GraffitiSession.actor | `actor`} URI to authenticate with.
  * However it is likely that the `session` object must contain other
  * implementation-specific properties.
  * For example, a Solid implementation might include a
@@ -197,7 +201,7 @@ export const GraffitiPutObjectJSONSchema = {
  * As to why the `session` object is passed as an argument to every method
  * rather than being an internal property of the {@link Graffiti} instance,
  * this is primarily for type-checking to catch bugs related to login state.
- * Graffiti applications can expose some functionality to users who are not logged in
+ * Graffiti applications can expose some functionality to people who are not logged in
  * with {@link Graffiti.get} and {@link Graffiti.discover} but without type-checking
  * the `session` it can be easy to forget to hide buttons that trigger
  * other methods that require login.
@@ -211,14 +215,14 @@ export const GraffitiPutObjectJSONSchema = {
  */
 export interface GraffitiSession {
   /**
-   * The {@link GraffitiObjectBase.actor | `actor`} a user wants to authenticate with.
+   * The {@link GraffitiObjectBase.actor | `actor`} to authenticate with.
    */
   actor: string;
   /**
    * A yet undefined property detailing what operations the session
-   * grants the user to perform. For example, to allow a user to
+   * grants the actor to perform. For example, to allow a actor to
    * read private messages from a particular set of channels or
-   * to allow the user to write object matching a particular schema.
+   * to allow the actor to write object matching a particular schema.
    */
   scope?: {};
 }
@@ -324,7 +328,7 @@ export interface GraffitiObjectStreamEntry<Schema extends JSONSchema> {
  * A result from a {@link GraffitiObjectStreamContinue} that indicated
  * an object has been deleted since the original stream was run.
  * Only sparse metadata about the deleted object is returned to respect
- * the deleting user's privacy.
+ * the deleting actor's privacy.
  *
  * @internal
  */
@@ -340,7 +344,7 @@ export interface GraffitiObjectStreamContinueTombstone {
   tombstone: true;
   /**
    * Sparse metadata about the deleted object. The full object is not returned
-   * to respect a user's privacy.
+   * to respect a actor's privacy.
    */
   object: {
     /**
@@ -377,7 +381,7 @@ export type GraffitiObjectStreamContinueEntry<Schema extends JSONSchema> =
  * that allows the stream to be continued from where it left off.
  *
  * The {@link continue} function preserves the typing of the original stream,
- * where as the {@link cursor} string can be serialized for use after a user
+ * where as the {@link cursor} string can be serialized for use after a person
  * has closed and reopened an application.
  *
  * The continued stream may include `tombstone`s of objects that have been
@@ -455,7 +459,7 @@ export type GraffitiChannelStatsStream = AsyncGenerator<
 
 /**
  * The event type produced in {@link Graffiti.sessionEvents}
- * when a user logs in manually from {@link Graffiti.login}
+ * when a actor logs in manually from {@link Graffiti.login}
  * or when their session is restored from a previous login.
  * The event name to listen for is `login`.
  */
@@ -472,7 +476,7 @@ export type GraffitiLoginEvent = CustomEvent<
 
 /**
  * The event type produced in {@link Graffiti.sessionEvents}
- * when a user logs out either manually with {@link Graffiti.logout}
+ * when a actor logs out either manually with {@link Graffiti.logout}
  * or when their session times out or otherwise becomes invalid.
  * The event name to listen for is `logout`.
  */
@@ -495,8 +499,8 @@ export type GraffitiLogoutEvent = CustomEvent<
  * their own {@link GraffitiLoginEvent} events.
  *
  * This event optionally returns an `href` property
- * representing the URL the user originated a login request
- * from, which may be useful for redirecting the user back to
+ * representing the URL that originated a login request,
+ * which may be useful for redirecting the user back to
  * the page they were on after login.
  * The event name to listen for is `initialized`.
  */