@oxyhq/contracts 0.23.0 → 0.25.0

package/dist/esm/followGraph.js

@@ -0,0 +1,27 @@
+/**
+ * The follow graph wire contract (`/v2/follows`).
+ *
+ * These types are the boundary between the API that owns the graph and every
+ * application that reads it. They live here — not in the API and not in the
+ * SDK — because both ends have to agree, and a shape defined on one side is a
+ * shape the other side re-declares slightly differently within a release or two.
+ *
+ * ## Why the state is three fields and not a boolean
+ *
+ * A user can follow something globally and turn it off in ONE application. That
+ * is a state the user themselves created, so the client has to be able to see
+ * it and say so — "following, but not shown here" is a sentence a boolean
+ * cannot express. `globalState`, `applicationMode` and `effectiveState` are
+ * therefore reported separately, and only the last one answers "does this
+ * appear in my feed right now".
+ *
+ * ## Why kinds are strings
+ *
+ * `FollowTargetKind` is a plain `string`, not a union. Applications register
+ * their own kinds at runtime (`mercaria.store`, `syra.artist`), so a union here
+ * would mean every new application in the ecosystem needs a release of this
+ * package before it can follow anything. The namespace rule is enforced by the
+ * database, which is the one place that can enforce it for applications this
+ * package has never heard of.
+ */
+export {};

package/dist/esm/oxyRecordTypes.js

@@ -1,26 +1,54 @@
 /**
  * Oxy-scoped signed-record types.
  *
- * The base `signedRecordEnvelopeSchema` (`./identity`) now treats `type` as an
- * OPEN, non-empty string so ANY Oxy app may define its own record categories
- * (e.g. `app.mention.*`'s `app_record`) on the shared envelope grammar. The Oxy
- * identity/civic/node STORE, however, accepts ONLY the closed set of categories
- * it knows how to verify and materialize — this module is that closed set.
+ * The base `signedRecordEnvelopeSchema` (`./identity`) treats `type` as an OPEN,
+ * non-empty string so ANY Oxy app may sign on the shared envelope grammar. The
+ * Oxy STORE re-narrows it to the closed set in this module — a `type` outside it
+ * is rejected as `invalid_envelope`.
  *
- * `oxySignedRecordTypeSchema` is the runtime gate the Oxy store re-narrows with
- * (the API's `verifyEnvelope` rejects any `type` outside it; the Mongoose
- * `SignedRecord.type` enum is derived from `.options`); `OxySignedRecordType` is
- * the matching compile-time union the SDK identity/civic mixins type against.
+ * `oxySignedRecordTypeSchema` is that runtime gate (the API's `verifyEnvelope`
+ * re-narrows with it; the Mongoose `SignedRecord.type` enum and the Postgres
+ * CHECK on `signed_records.type` are both derived from `.options`);
+ * `OxySignedRecordType` is the matching compile-time union the SDK
+ * identity/civic mixins type against.
  *
  * The signing input INCLUDES `type`, so this set is part of the signed bytes —
- * a record cannot have its category swapped after signing.
+ * a record cannot have its category swapped after signing, and a value once
+ * signed can never be renamed.
  *
  * v1 only ever carried `identity` / `profile` (already in production); v2 added
  * the civic record types (reputation attestations, real-life / peer validations,
  * personhood vouches, verifiable credentials) and the user-node registration
- * record. Every value here is an Oxy `app.oxy.*` (or legacy v1) category — an
- * app's own `type` (e.g. `app_record`) is intentionally NOT in this set and is
- * rejected by the Oxy store.
+ * record.
+ *
+ * ## Why `app_record` is here, when it deliberately was not
+ *
+ * This set used to hold Oxy's own categories only, and said so: an app's `type`
+ * was "intentionally NOT in this set". The reason given was that the store
+ * accepts only what it knows how to **verify and materialize**. Verification
+ * turned out not to argue for the exclusion — the engine verifies a signature
+ * against the subject's keys whatever the category says — and materialization
+ * is the app's job, not the store's: an app projects its own feed tables from
+ * records it reads back.
+ *
+ * What changed is the decision the exclusion blocked. One chain per PERSON, held
+ * by Oxy, is the ecosystem substrate: apps append their records to the subject's
+ * one chain instead of each keeping a private chain for the same person. A
+ * closed set that admits no app category makes that unrepresentable.
+ *
+ * `app_record` is ONE value rather than an open lane, and the lexicon lives in
+ * the envelope's `collection` (`app.mention.feed.post`, `app.syra.*`), which the
+ * store denormalizes to `signed_records.nsid` and indexes. So a new app needs no
+ * change here — it picks its own collection namespace and signs `app_record`,
+ * exactly as Mention already does in production. Keeping the set closed is what
+ * keeps the CHECK a real constraint.
+ *
+ * **Admitting the category is not the whole of that decision.** Two gates sit
+ * beside it and are unchanged: an app record must arrive as a v2 (chained)
+ * envelope, and `oxyVerificationResolver` accepts exactly one custodial issuer
+ * (`OXY_DID`). So a record a user signs themselves verifies here today, while
+ * one an app signs custodially under its OWN issuer DID does not — that needs a
+ * separate, deliberate answer about which issuers may write to a person's chain.
  *
  * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
  */
@@ -34,4 +62,7 @@ export const oxySignedRecordTypeSchema = z.enum([
     'personhood_vouch',
     'credential',
     'node',
+    // Any Oxy app's own record. The LEXICON is the envelope's `collection`, not
+    // this value — see the header.
+    'app_record',
 ]);