@oxy.so/contracts 1.0.0

package/dist/esm/moderationReputation.js

@@ -0,0 +1,295 @@
+/**
+ * Oxy Trust — the moderation reputation bridge (CrowdSource → Oxy Trust).
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shapes crossing the one-way boundary
+ * between a participatory-moderation service and the Oxy reputation ledger.
+ *
+ * The direction is not negotiable: a moderation service NEVER writes reputation.
+ * It emits an authenticated internal event describing a decision it published,
+ * and Oxy's own consequence engine validates that event and derives the effect.
+ * Everything in this module is therefore either (a) the event, (b) the receipt
+ * the engine returns, or (c) the derived state the engine publishes back to the
+ * subject.
+ *
+ * Design anchors, all load-bearing:
+ *
+ *  - **Conduct is a separate axis from contribution.** A conduct penalty raises
+ *    `activeRisk` and creates a strike; positive contribution points can never
+ *    cancel a strike, because standing is derived from active risk and not from
+ *    the point total. See {@link ReputationConduct}.
+ *  - **The reporting axis carries only reporting signals.** `abuseScore` on the
+ *    legacy reliability block conflated rejected reports with every negative
+ *    transaction; {@link ReputationReporting} exists so a conduct penalty can
+ *    never inflate a report-abuse figure.
+ *  - **No binding proof, no effect.** {@link ModerationDecisionEventSubject}
+ *    requires a `bindingProofId`, and the engine rejects an event whose binding
+ *    does not resolve to the claimed principal at or before `occurredAt`. An
+ *    application cannot move a reputation figure by naming a user id.
+ *  - **One penalty per incident.** The idempotency key is
+ *    `moderation:<incidentId>:<decisionRevision>:<effectType>`; a hundred
+ *    reports about the same material produce one effect.
+ *  - **Every effect carries the policy version it was decided under**, so a
+ *    consequence can be recomputed under the original policy rather than under
+ *    whatever the current tuning happens to be.
+ *
+ * Platform-agnostic — zod only. ESM-safe (no `require()`).
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/*  Closed value sets                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Severity band of a moderation finding, lowest → highest.
+ *
+ * The band — not the taxonomy code — is what the consequence engine consumes:
+ * points, active risk and expiry are all keyed by severity in the versioned
+ * conduct policy, so a new taxonomy code needs no engine change and no
+ * intimate category ever reaches the ledger.
+ */
+export const MODERATION_SEVERITIES = ['low', 'medium', 'high', 'critical'];
+export const moderationSeveritySchema = z.enum(MODERATION_SEVERITIES);
+/**
+ * How far a finding reaches.
+ *
+ * - `application_local`   — the application enforces locally; Oxy Trust is NOT
+ *   touched. Emitted for completeness; the engine rejects the effect.
+ * - `oxy_network`         — conduct against the Oxy network as a whole.
+ * - `identity_integrity`  — impersonation, sybil behaviour, credential abuse.
+ *
+ * Only `oxy_network` and `identity_integrity` can produce a global effect.
+ */
+export const MODERATION_FINDING_SCOPES = [
+    'application_local',
+    'oxy_network',
+    'identity_integrity',
+];
+export const moderationFindingScopeSchema = z.enum(MODERATION_FINDING_SCOPES);
+/** Which participant in the reported material the finding attributes to. */
+export const MODERATION_ATTRIBUTIONS = ['author', 'sharer', 'reporter', 'reviewer'];
+export const moderationAttributionSchema = z.enum(MODERATION_ATTRIBUTIONS);
+/**
+ * Lifecycle of the decision the event describes.
+ *
+ * `inconclusive` is its own outcome and never collapses into "no violation";
+ * it simply produces no effect. `superseded` and `corrected` describe a
+ * revision that a later one replaced — an event in either state is rejected,
+ * because applying it would resurrect a consequence the appeal removed.
+ */
+export const MODERATION_DECISION_STATUSES = [
+    'provisional',
+    'final',
+    'inconclusive',
+    'superseded',
+    'corrected',
+];
+export const moderationDecisionStatusSchema = z.enum(MODERATION_DECISION_STATUSES);
+/**
+ * The kind of consequence an effect carries. Each is its own axis, and the
+ * idempotency key includes it — one incident may legitimately produce a conduct
+ * effect for the author AND a report-abuse effect for a malicious reporter.
+ */
+export const MODERATION_EFFECT_TYPES = [
+    'conduct_penalty',
+    'report_abuse_penalty',
+    'review_abuse_penalty',
+];
+export const moderationEffectTypeSchema = z.enum(MODERATION_EFFECT_TYPES);
+/** Lifecycle of a stored effect. */
+export const MODERATION_EFFECT_STATUSES = ['applied', 'reversed'];
+export const moderationEffectStatusSchema = z.enum(MODERATION_EFFECT_STATUSES);
+/** Lifecycle of a conduct strike. Only `active` strikes carry active risk. */
+export const CONDUCT_STRIKE_STATUSES = ['active', 'expired', 'reversed'];
+export const conductStrikeStatusSchema = z.enum(CONDUCT_STRIKE_STATUSES);
+/**
+ * Conduct standing, derived from ACTIVE RISK and nothing else.
+ *
+ * Deliberately independent of the point total: a person may hold a high
+ * contribution tier and a `limited` standing at the same time, and earning
+ * points cannot move standing back toward `good`. Only expiry or reversal can.
+ */
+export const CONDUCT_STANDINGS = ['good', 'watch', 'limited', 'restricted'];
+export const conductStandingSchema = z.enum(CONDUCT_STANDINGS);
+/** Contribution tier, derived from contribution points only. */
+export const CONTRIBUTION_TIERS = ['new', 'trusted', 'high_trust'];
+export const contributionTierSchema = z.enum(CONTRIBUTION_TIERS);
+/** Personhood status. Being a real person proves neither conduct nor competence. */
+export const PERSONHOOD_STATUSES = ['unknown', 'probable', 'verified'];
+export const personhoodStatusSchema = z.enum(PERSONHOOD_STATUSES);
+/**
+ * How an Oxy identity was bound to the actor an application reported.
+ *
+ * - `oauth_grant`        — the user authorized the application through Oxy's own
+ *   OAuth flow. Oxy wrote the record; the application asserts nothing.
+ * - `session_proof`      — the application presented the USER'S OWN Oxy access
+ *   token alongside its service credential, proving the user was present in
+ *   that application under a named local principal id.
+ * - `commons_signature`  — a DID-verifiable signature over a server-issued nonce.
+ * - `federated_actor`    — a resolvable, authorized federated actor link.
+ */
+export const IDENTITY_BINDING_TYPES = [
+    'oauth_grant',
+    'session_proof',
+    'commons_signature',
+    'federated_actor',
+];
+export const identityBindingTypeSchema = z.enum(IDENTITY_BINDING_TYPES);
+/** Binding lifecycle. A revoked binding proves nothing about a later action. */
+export const IDENTITY_BINDING_STATUSES = ['active', 'revoked'];
+export const identityBindingStatusSchema = z.enum(IDENTITY_BINDING_STATUSES);
+/**
+ * An application's own moderation standing. An external application can abuse
+ * the system too, so it carries standing exactly like a person does.
+ *
+ * `sandbox` applications moderate locally and produce NO global effect.
+ */
+export const APPLICATION_MODERATION_STANDINGS = ['sandbox', 'trusted', 'restricted'];
+export const applicationModerationStandingSchema = z.enum(APPLICATION_MODERATION_STANDINGS);
+/**
+ * Why the engine declined to apply an effect.
+ *
+ * Returned rather than thrown for the cases that are a legitimate outcome of a
+ * well-formed event (a sandboxed application, a local-only finding, an
+ * inconclusive decision): the emitter must be able to record "delivered, no
+ * effect" and stop retrying. Malformed or unauthorized events are HTTP errors,
+ * not skip reasons.
+ */
+export const MODERATION_EFFECT_SKIP_REASONS = [
+    'no_binding_proof',
+    'binding_after_action',
+    'binding_principal_mismatch',
+    'binding_revoked',
+    'decision_not_effective',
+    'decision_superseded',
+    'finding_scope_local',
+    'finding_not_in_policy',
+    'application_not_permitted',
+    'no_effective_finding',
+];
+export const moderationEffectSkipReasonSchema = z.enum(MODERATION_EFFECT_SKIP_REASONS);
+export const moderationFindingSchema = z.object({
+    code: z.string().trim().min(1).max(200),
+    severity: moderationSeveritySchema,
+    scope: moderationFindingScopeSchema,
+    attribution: moderationAttributionSchema,
+    family: z.string().trim().min(1).max(100),
+});
+export const moderationDecisionEventSubjectSchema = z.object({
+    principalType: z.literal('oxy_user'),
+    principalId: z.string().trim().min(1),
+    bindingProofId: z.string().trim().min(1),
+});
+export const moderationPolicyVersionsSchema = z.object({
+    universal: z.string().trim().min(1).max(100),
+    application: z.string().trim().min(1).max(100),
+    oxyConduct: z.string().trim().min(1).max(100),
+});
+export const moderationDecisionEventSchema = z.object({
+    eventId: z.string().trim().min(1).max(200),
+    reportedApplicationId: z.string().trim().min(1).max(200),
+    type: z.string().trim().min(1).max(200),
+    caseId: z.string().trim().min(1).max(200),
+    incidentId: z.string().trim().min(1).max(200),
+    decisionId: z.string().trim().min(1).max(200),
+    decisionRevision: z.number().int().min(1),
+    subject: moderationDecisionEventSubjectSchema,
+    findings: z.array(moderationFindingSchema).min(1).max(20),
+    decisionStatus: moderationDecisionStatusSchema,
+    policyVersions: moderationPolicyVersionsSchema,
+    occurredAt: z.string().trim().min(1),
+    proofHash: z.string().trim().min(1).max(200),
+});
+export const finalizeModerationDecisionSchema = z.object({
+    decisionId: z.string().trim().min(1).max(200),
+    decisionRevision: z.number().int().min(1),
+});
+export const reverseModerationEffectSchema = z.object({
+    decisionId: z.string().trim().min(1).max(200),
+    decisionRevision: z.number().int().min(1),
+    reason: z.string().trim().min(1).max(500),
+});
+export const moderationEffectSchema = z.object({
+    id: z.string(),
+    incidentId: z.string(),
+    caseId: z.string(),
+    decisionId: z.string(),
+    decisionRevision: z.number(),
+    principalId: z.string(),
+    effectType: moderationEffectTypeSchema,
+    status: moderationEffectStatusSchema,
+    points: z.number(),
+    activeRisk: z.number(),
+    severity: moderationSeveritySchema,
+    repetitionMultiplier: z.number(),
+    multiFindingMultiplier: z.number(),
+    idempotencyKey: z.string(),
+    transactionId: z.string(),
+    strikeId: z.string().optional(),
+    reversalTransactionId: z.string().optional(),
+    policyVersions: moderationPolicyVersionsSchema,
+    appliedAt: z.string(),
+    reversedAt: z.string().optional(),
+});
+export const applyModerationDecisionResultSchema = z.object({
+    applied: z.boolean(),
+    effect: moderationEffectSchema.optional(),
+    skipReason: moderationEffectSkipReasonSchema.optional(),
+    idempotent: z.boolean(),
+});
+export const reverseModerationEffectResultSchema = z.object({
+    reversed: z.array(moderationEffectSchema),
+    idempotent: z.boolean(),
+});
+export const registerIdentityBindingSchema = z.object({
+    localPrincipalId: z.string().trim().min(1).max(200),
+    userProofToken: z.string().trim().min(1),
+});
+export const identityBindingSchema = z.object({
+    id: z.string(),
+    applicationId: z.string(),
+    userId: z.string(),
+    localPrincipalId: z.string(),
+    bindingType: identityBindingTypeSchema,
+    status: identityBindingStatusSchema,
+    verifiedAt: z.string(),
+    createdAt: z.string(),
+});
+export const reputationPersonhoodSchema = z.object({
+    status: personhoodStatusSchema,
+    score: z.number(),
+});
+export const reputationContributionSchema = z.object({
+    points: z.number(),
+    tier: contributionTierSchema,
+});
+export const reputationConductSchema = z.object({
+    standing: conductStandingSchema,
+    activeRisk: z.number(),
+    activeStrikes: z.number(),
+    nextExpiryAt: z.string().optional(),
+});
+export const reputationReportingSchema = z.object({
+    reliability: z.number(),
+    confidence: z.number(),
+    confirmed: z.number(),
+    rejected: z.number(),
+    malicious: z.number(),
+});
+export const reputationReviewingSchema = z.object({
+    globalReliability: z.number(),
+    categoryReliability: z.record(z.number()),
+    languageReliability: z.record(z.number()),
+});
+export const reputationContextualInfluenceSchema = z.object({
+    reportPriorityWeight: z.number(),
+    reviewSelectionWeight: z.number(),
+    rankingWeight: z.number(),
+});
+export const applicationModerationTrustSchema = z.object({
+    applicationId: z.string(),
+    standing: applicationModerationStandingSchema,
+    evidenceIntegrity: z.number(),
+    identityBindingReliability: z.number(),
+    decisionOverturnRate: z.number(),
+    policyQuality: z.number(),
+    globalReputationEffectsAllowed: z.boolean(),
+});

package/dist/esm/oauth.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+/**
+ * The two `/auth/oauth/*` responses the browser hub's edge layer reads.
+ *
+ * They existed on the wire long before this file — `GET /auth/oauth/consent`
+ * and `POST /auth/oauth/authorize` are the surface `auth.oxy.so` has always
+ * driven with a bearer. What is new (issue #937 Phase 5) is a SECOND consumer
+ * that is not the SPA: the IdP's edge layer runs both calls server-side so the
+ * device-wide bearer never enters the browser's script context. A shape read by
+ * two independently deployed consumers is a contract, so it is written down
+ * once here and validated on both sides rather than transcribed into the edge.
+ *
+ * These are NOT the RFC 6749 token/userinfo responses. Those two speak flat
+ * OAuth/OIDC on the wire and are the one place in the API that does not use the
+ * `{ data }` envelope; these two are ordinary internal API responses that happen
+ * to be about OAuth.
+ */
+/**
+ * Server-authoritative answer to "must this user be shown a consent screen".
+ *
+ * Discriminated on `consentRequired` so the two arms cannot be confused by a
+ * consumer that reads `reason` first: `trusted`/`granted` are reasons NOT to
+ * ask, `new`/`scope_changed` are reasons to ask, and a flat object would let a
+ * typo in one produce a plausible value of the other.
+ *
+ *  - `trusted`       — the application is first-party/internal/system/official
+ *                      by the REGISTRY's verdict (`isTrustedApplication`), and
+ *                      the request names no scope over the user's own follow
+ *                      graph. Never inferred from a hostname.
+ *  - `granted`       — a prior `AppGrant` already covers every requested scope.
+ *  - `scope_changed` — a prior grant exists and is missing one.
+ *  - `new`           — no prior grant.
+ *
+ * `userConsentScopes` names the scopes that FORCED the screen, so the consent UI
+ * can say which one it is asking about. Present only on the `true` arm, and only
+ * when such a scope exists — a trusted app asked for one is still asked.
+ */
+export const oauthConsentDecisionSchema = z.discriminatedUnion('consentRequired', [
+    z.object({
+        consentRequired: z.literal(false),
+        reason: z.enum(['trusted', 'granted']),
+    }),
+    z.object({
+        consentRequired: z.literal(true),
+        reason: z.enum(['new', 'scope_changed']),
+        userConsentScopes: z.array(z.string()).optional(),
+    }),
+]);
+/**
+ * A minted authorization code.
+ *
+ * `state` is echoed back as the caller sent it and is `null` when they sent
+ * none — never omitted, so a consumer cannot read "the server dropped my state"
+ * as "I sent none". `redirectUri` is echoed for the same reason the code is
+ * bound to it server-side: the caller must be able to see that the value the
+ * code was issued against is the one it registered.
+ */
+export const oauthAuthorizeCodeResponseSchema = z.object({
+    code: z.string().min(1),
+    state: z.string().nullable(),
+    redirectUri: z.string(),
+    expiresIn: z.number().int().positive(),
+});

package/dist/esm/oxyRecordTypes.js

@@ -0,0 +1,68 @@
+/**
+ * Oxy-scoped signed-record types.
+ *
+ * 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 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, 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.
+ *
+ * ## 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.
+ */
+import { z } from 'zod';
+export const oxySignedRecordTypeSchema = z.enum([
+    'identity',
+    'profile',
+    'reputation_attestation',
+    'real_life_attestation',
+    'validation_verdict',
+    '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',
+]);

package/dist/esm/protocol.js

@@ -0,0 +1,50 @@
+/**
+ * Generic "Oxy Protocol" record surface — the app-agnostic conventions every app
+ * follows to decentralize its own content on the shared signed-record substrate.
+ *
+ * The base `signedRecordEnvelopeSchema` (`./identity`) is the WIRE grammar: a
+ * signed envelope whose `type` is an open string and whose `record` is an opaque
+ * `Record<string, unknown>`. An app layers its own LEXICON on top of that
+ * grammar — a typed projection of the `record` payload, addressed by an
+ * AtProto-style `(collection, rkey)` key — WITHOUT forking the envelope schema.
+ *
+ * ## Recipe — defining an app lexicon record
+ *
+ * For each record kind an app wants to publish:
+ *
+ * 1. Define the `record` PAYLOAD schema as a `z.ZodType<XPayload>` (e.g.
+ *    `app.mention.feed.post` → `mentionPostRecordSchema: z.ZodType<MentionPost>`).
+ *    This validates ONLY the inner `record`, not the envelope.
+ * 2. Declare the `collection` NSID as a constant (e.g.
+ *    `export const MENTION_POST_COLLECTION = 'app.mention.feed.post'`).
+ * 3. Reuse the UNCHANGED {@link signedRecordEnvelopeSchema} for the envelope. The
+ *    base treats `record` as `z.record(z.unknown())`, so the app validates the
+ *    envelope with the base schema first, then parses `envelope.record` with its
+ *    own payload schema. {@link LexiconRecord} is the typed projection that pairs
+ *    the `(collection, rkey)` key with the parsed payload.
+ *
+ * The Oxy civic contracts (`./civic`) already follow this convention implicitly:
+ * each civic record (`real_life_attestation`, `personhood_vouch`, `credential`,
+ * …) ships a `record`-payload schema and is carried by the base envelope.
+ *
+ * ## Chain-wire shapes
+ *
+ * {@link ChainHeadResponse} and {@link LogPageResponse} are the shared response
+ * shapes every chain store exposes (Oxy's `GET /identity/records/:userId/chain/head`,
+ * `GET /identity/head/:userId`, `GET /identity/log/:userId`, and any app node's
+ * equivalents). They are defined ONCE here so producers and consumers (the API
+ * handlers, the SDK identity/nodes mixins, app nodes) cannot drift.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+import { signedRecordEnvelopeSchema } from './identity.js';
+export const chainHeadResponseSchema = z.object({
+    headRecordId: z.string().nullable(),
+    seq: z.number().int(),
+    recordCount: z.number().int().nonnegative(),
+});
+export const logPageResponseSchema = z.object({
+    records: z.array(signedRecordEnvelopeSchema),
+    count: z.number().int().nonnegative(),
+});

package/dist/esm/recommendations.js

@@ -0,0 +1,165 @@
+/**
+ * Recommendation-engine API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the reputation-weighted
+ * profile-recommendation surface (`POST /profiles/recommendations`) and the
+ * cross-app signal-ingest endpoint (`POST /app-signals/ingest`). The API
+ * validates its INPUT/OUTPUT against these schemas; consumer SDKs validate the
+ * same definitions, so the producer and every consumer cannot drift.
+ *
+ * Platform-agnostic — zod is the only runtime dependency (no react / react-native
+ * / expo, ESM-safe).
+ */
+import { z } from 'zod';
+import { userNameSchema } from './userResponse.js';
+/** User-type filters a caller may exclude from the recommendation surface. */
+export const recommendationExcludeTypeSchema = z.enum([
+    'federated',
+    'agent',
+    'automated',
+]);
+/**
+ * A caller-supplied editorial boost. `userIds` are nudged up (or down, for a
+ * negative weight) in the ranking; the optional `reason` is for audit/telemetry
+ * only and never surfaced to end users. Boost members still pass the eligibility
+ * gate — a boost cannot resurrect a private/restricted/ineligible account.
+ */
+export const recommendationBoostSchema = z.object({
+    userIds: z.array(z.string().trim().min(1)).min(1).max(200),
+    weight: z.number().min(-5).max(5),
+    reason: z.string().trim().max(120).optional(),
+});
+/**
+ * Per-request overrides for the scoring signal weights. Every key is optional
+ * and clamped server-side to the resolved weight profile's allowed range — a
+ * caller can re-weight signals but never escape the profile's bounds.
+ */
+export const recommendationSignalWeightsSchema = z
+    .object({
+    graph: z.number().min(0).max(10).optional(),
+    completeness: z.number().min(0).max(10).optional(),
+    verified: z.number().min(0).max(10).optional(),
+    curation: z.number().min(0).max(10).optional(),
+    interest: z.number().min(0).max(10).optional(),
+    appBoost: z.number().min(0).max(10).optional(),
+    repCandidate: z.number().min(0).max(10).optional(),
+    affinity: z.number().min(0).max(10).optional(),
+})
+    .partial();
+/**
+ * Request body for `POST /profiles/recommendations`.
+ *
+ * `clientId` selects the per-app weight profile (the Application `_id`); when
+ * omitted the default profile is used. `excludeIds` removes accounts the caller
+ * has already seen/handled; `boosts` and `signalWeights` let the caller bias the
+ * ranking within server-enforced bounds.
+ */
+export const recommendationRequestSchema = z.object({
+    clientId: z.string().trim().min(1).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+    offset: z.number().int().min(0).optional(),
+    excludeTypes: z.array(recommendationExcludeTypeSchema).optional(),
+    excludeIds: z.array(z.string().trim().min(1)).max(500).optional(),
+    boosts: z.array(recommendationBoostSchema).max(50).optional(),
+    signalWeights: recommendationSignalWeightsSchema.optional(),
+});
+/** Follower/following counts attached to a recommendation item. */
+export const recommendationCountSchema = z.object({
+    followers: z.number().int().nonnegative(),
+    following: z.number().int().nonnegative(),
+});
+/**
+ * A single recommended profile.
+ *
+ * `name` reuses the canonical {@link userNameSchema} so `name.displayName` is the
+ * already-resolved server-side value. `score` and `matchedSignals` are present
+ * only on the scored (v2) path; `mutualCount` and `_count` are always present.
+ */
+export const recommendationItemSchema = z
+    .object({
+    id: z.string(),
+    username: z.string().optional(),
+    name: userNameSchema,
+    avatar: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    verified: z.boolean().optional(),
+    trustTier: z.string().optional(),
+    mutualCount: z.number().int().nonnegative(),
+    score: z.number().optional(),
+    matchedSignals: z.array(z.string()).optional(),
+    isFederated: z.boolean().optional(),
+    isAgent: z.boolean().optional(),
+    isAutomated: z.boolean().optional(),
+    instance: z.string().optional(),
+    _count: recommendationCountSchema,
+})
+    .passthrough();
+/** Wire shape of the recommendation response — an array of items. */
+export const recommendationResponseSchema = z.array(recommendationItemSchema);
+/** One endorsement edge an app reports: `ownerId` endorses `memberId`. */
+export const appEndorsementInputSchema = z.object({
+    ownerId: z.string().trim().min(1),
+    memberId: z.string().trim().min(1),
+    op: z.enum(['add', 'remove']).default('add'),
+    sourceId: z.string().trim().min(1).optional(),
+});
+/** One interest signal an app reports: how interested `userId` is in a topic. */
+export const appInterestInputSchema = z.object({
+    userId: z.string().trim().min(1),
+    interestScore: z.number().min(0).max(1),
+});
+/**
+ * Request body for `POST /app-signals/ingest` (service token, `signals:write`).
+ *
+ * At least one of `endorsements` / `interests` must be non-empty — an ingest
+ * with neither is a no-op and rejected so a misconfigured caller is surfaced
+ * rather than silently succeeding.
+ */
+export const appUserSignalIngestSchema = z
+    .object({
+    endorsements: z.array(appEndorsementInputSchema).max(500).optional(),
+    interests: z.array(appInterestInputSchema).max(500).optional(),
+})
+    .refine((value) => (value.endorsements?.length ?? 0) > 0 || (value.interests?.length ?? 0) > 0, { message: 'At least one of endorsements or interests must be non-empty' });
+/**
+ * The directed interaction types a consuming app may report between two users.
+ * Each type carries a server-side default weight (see the API's
+ * `AFFINITY_EVENT_WEIGHTS`); a caller may override the applied weight per event.
+ */
+export const appAffinityEventTypeSchema = z.enum([
+    'like',
+    'reply',
+    'boost',
+    'follow',
+    'mention',
+    'profile_view',
+    'quote',
+    'repost',
+]);
+/**
+ * One directed interaction event: `fromUserId` interacted with `toUserId`
+ * (`type`) at `occurredAt`. The Oxy affinity-graph folds these into a per-app,
+ * time-decayed directed affinity edge (`fromUserId → toUserId`).
+ *
+ * - `weight` (optional) overrides the per-type default weight for this event.
+ * - `occurredAt` (optional, ISO) is the event time; absent means "now" at ingest.
+ * - `eventId` (optional) makes an event idempotent — a repeated `eventId` for the
+ *   same application is folded at most once (bounded dedup window).
+ */
+export const appAffinityEventSchema = z.object({
+    fromUserId: z.string().trim().min(1),
+    toUserId: z.string().trim().min(1),
+    type: appAffinityEventTypeSchema,
+    weight: z.number().min(0).max(100).optional(),
+    occurredAt: z.string().datetime().optional(),
+    eventId: z.string().trim().min(1).max(200).optional(),
+});
+/**
+ * Request body for `POST /app-signals/events` (service token, `signals:write`).
+ *
+ * A non-empty batch (1..1000) of directed interaction events for the requesting
+ * application. Self-edges (`fromUserId === toUserId`) are dropped server-side.
+ */
+export const appAffinityEventsIngestSchema = z.object({
+    events: z.array(appAffinityEventSchema).min(1).max(1000),
+});