@buildinternet/releases-api-types 0.36.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/releases-api-types",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Wire protocol — request/response types for the Releases registry API. Shared by web, workers, and clients.",
   "type": "module",
   "license": "MIT",

package/src/api-types.ts

@@ -24,6 +24,8 @@ import type {
   ReleaseSummaryItemSchema,
   OverviewPageItemSchema,
   OverviewCitationSchema,
+  OrgStatusSchema,
+  ReleaseLocationItemSchema,
 } from "./schemas/shared.js";
 import type {
   OrgListItemSchema,
@@ -263,6 +265,8 @@ export {
   ReleaseSummaryItemSchema,
   OverviewPageItemSchema,
   OverviewCitationSchema,
+  OrgStatusSchema,
+  ReleaseLocationItemSchema,
   CategorySchema,
   NoticeSchema,
 } from "./schemas/shared.js";
@@ -308,11 +312,28 @@ export {
   WorkspaceProfileResponseSchema,
 } from "./schemas/account-profile.js";
 export {
+  CreateStubOrgBodySchema,
+  StubFromDomainBodySchema,
   ReleasesJsonConfigSchema,
+  ReleasesJsonDomainReleaseSchema,
+  ReleasesJsonDomainSchema,
   ReleasesJsonProductSchema,
+  ReleasesJsonRegistriesSchema,
+  ReleasesJsonRepoProductSchema,
+  ReleasesJsonRepoReleaseSchema,
+  ReleasesJsonRepoSchema,
   SyncWellKnownResponseSchema,
 } from "./schemas/well-known.js";
-export type { ReleasesJsonConfig, ReleasesJsonProduct } from "./schemas/well-known.js";
+export type {
+  CreateStubOrgBody,
+  StubFromDomainBody,
+  ReleasesJsonConfig,
+  ReleasesJsonDomain,
+  ReleasesJsonDomainRelease,
+  ReleasesJsonProduct,
+  ReleasesJsonRepo,
+  ReleasesJsonRepoRelease,
+} from "./schemas/well-known.js";
 export {
   SourceListItemSchema,
   SourceWithOrgSchema,
@@ -509,6 +530,11 @@ export type { ResolveResponse } from "./schemas/resolve.js";
 
 export type MediaItem = z.infer<typeof MediaItemSchema>;
 
+// ── Stub tier (#1947) ──
+
+export type OrgStatus = z.infer<typeof OrgStatusSchema>;
+export type ReleaseLocationItem = z.infer<typeof ReleaseLocationItemSchema>;
+
 // ── Stats ──
 
 export type Stats = z.infer<typeof StatsSchema>;
@@ -766,6 +792,12 @@ export interface WhatsChangedEntry {
   breaking: BreakingLevel;
   migrationNotes: string | null;
   url: string | null;
+  /**
+   * Absolute canonical web URL — the slugged `/release/<id>-<slug>` form
+   * (#1906), built from `WEB_BASE_URL`. Distinct from `url` (the upstream
+   * source URL); lets an upgrade-planning agent link the release detail page.
+   */
+  webUrl: string | null;
 }
 
 /**

package/src/schemas/lookups.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import { CategorySchema } from "./shared.js";
+import { CategorySchema, OrgStatusSchema, ReleaseLocationItemSchema } from "./shared.js";
 
 /**
  * Status flags returned by `POST /v1/lookups`:
@@ -104,6 +104,14 @@ export const DomainLookupOrgSchema = z.object({
   category: z.string().nullable(),
   avatarUrl: z.string().nullable(),
   matchedVia: z.enum(["primary", "alias"]),
+  /** Org tier (#1947). Optional for mid-deploy tolerance; absent ⇒ `"tracked"`. */
+  status: OrgStatusSchema.optional(),
+  /**
+   * Declared release locations (#1947) for a stub org — the "check these
+   * locations" answer when the domain resolves to an org with no sources yet.
+   * Omitted/empty for a tracked org.
+   */
+  locations: z.array(ReleaseLocationItemSchema).optional(),
 });
 
 export const DomainLookupProductSchema = z.object({

package/src/schemas/orgs.ts

@@ -6,9 +6,11 @@ import {
   CategorySchema,
   ListResponseSchema,
   NoticeSchema,
+  OrgStatusSchema,
   OverviewPageItemSchema,
   PaginationSchema,
   ReleaseItemSchema,
+  ReleaseLocationItemSchema,
   VideoSourceInfoSchema,
 } from "./shared.js";
 import { SourceListItemSchema } from "./sources.js";
@@ -24,6 +26,12 @@ export const OrgListItemSchema = z.object({
   category: CategorySchema.nullable(),
   avatarUrl: z.string().nullable(),
   featured: z.boolean(),
+  /**
+   * Org tier (#1947). Optional for mid-deploy tolerance; absent ⇒ `"tracked"`.
+   * A `"stub"` org has no processed sources yet — the UI renders a badge and a
+   * stub is excluded from release-ranked surfaces.
+   */
+  status: OrgStatusSchema.optional(),
   sourceCount: z.number().int().min(0),
   releaseCount: z.number().int().min(0),
   recentReleaseCount: z.number().int().min(0),
@@ -480,6 +488,18 @@ export const OrgDetailSchema = z.object({
   fetchPaused: z.boolean().optional(),
   /** How the org row was created. `on_demand` orgs are excluded from overview generation regardless of `autoGenerateContent`. */
   discovery: z.enum(["curated", "agent", "on_demand"]).optional(),
+  /**
+   * Org tier (#1947). Optional for mid-deploy tolerance; absent ⇒ `"tracked"`.
+   * A `"stub"` org's `sources` array is empty — `locations` carries the declared
+   * release locations instead.
+   */
+  status: OrgStatusSchema.optional(),
+  /**
+   * Declared release locations (#1947), present (and non-empty) for stub orgs.
+   * Same shape as a releases.json `releases[]` entry plus `basis`/`sourceId`.
+   * Omitted or empty for a tracked org with no locators.
+   */
+  locations: z.array(ReleaseLocationItemSchema).optional(),
   tags: z.array(z.string()).optional(),
   sourceCount: z.number().int().min(0),
   releaseCount: z.number().int().min(0),

package/src/schemas/overviews.ts

@@ -11,23 +11,19 @@ export const OrgOverviewResponseSchema = OverviewPageItemSchema.extend({
 }).nullable();
 
 /**
- * Incoming citation row attached to `POST /v1/orgs/:slug/overview`. Slimmer
- * than the read-side `OverviewCitationSchema` because the wire shape doesn't
- * carry `releaseId` — that's resolved server-side from `sourceUrl`. Spans
- * must be in-range (`endIndex > startIndex`); the cross-field
- * `endIndex <= content.length` check stays in the handler.
+ * Incoming citation row attached to `POST /v1/orgs/:slug/overview`. A source the
+ * overview drew on — just `sourceUrl` (+ optional display `title`); `releaseId`
+ * is resolved server-side from `sourceUrl`. The legacy body-offset fields
+ * (`startIndex`/`endIndex`/`citedText`) are accepted-but-ignored for wire
+ * back-compat with older clients (#1934); they're no longer stored.
  */
-export const IncomingOverviewCitationSchema = z
-  .object({
-    startIndex: z.number().int().min(0),
-    endIndex: z.number().int().min(1),
-    sourceUrl: z.string().min(1),
-    title: z.string().nullable().optional(),
-    citedText: z.string().min(1),
-  })
-  .refine((c) => c.endIndex > c.startIndex, {
-    message: "endIndex must be > startIndex",
-  });
+export const IncomingOverviewCitationSchema = z.object({
+  sourceUrl: z.string().min(1),
+  title: z.string().nullable().optional(),
+  startIndex: z.number().int().min(0).optional(),
+  endIndex: z.number().int().min(0).optional(),
+  citedText: z.string().optional(),
+});
 
 /**
  * Body accepted by `POST /v1/orgs/:slug/overview` — the agent-authored

package/src/schemas/shared.ts

@@ -44,6 +44,37 @@ export const VideoSourceInfoSchema = z.object({
   provider: z.enum(["youtube", "vimeo", "wistia"]),
 });
 
+/**
+ * Org tier surfaced on read paths (#1947). `stub` = known only by declared
+ * release locations (no processed sources yet); `tracked` = a normal org whose
+ * sources fetch. The column is `organizations.tier`; the wire name is `status`.
+ * Optional on the wire so a pinned client mid-deploy tolerates its absence —
+ * treat a missing value as `"tracked"`.
+ */
+export const OrgStatusSchema = z.enum(["stub", "tracked"]);
+
+/**
+ * A declared release location (#1947) — one `release_locations` row on the
+ * wire, the same shape a releases.json `releases[]` entry carries plus its
+ * provenance `basis` and, once promoted, the `sourceId` it materialized into.
+ * Surfaced on stub orgs so an agent gets "release info is published at these
+ * locations" instead of an empty sources list.
+ */
+export const ReleaseLocationItemSchema = z.object({
+  url: z.string().optional(),
+  feed: z.string().optional(),
+  github: z.string().optional(),
+  appstore: z.string().optional(),
+  file: z.string().optional(),
+  title: z.string().nullable().optional(),
+  canonical: z.boolean(),
+  basis: z.enum(["curator", "declared", "detected", "generated"]),
+  /** Owning product id when the locator is product-scoped, else null. */
+  productId: z.string().nullable(),
+  /** Set once the locator has been promoted into a source, else null. */
+  sourceId: z.string().nullable(),
+});
+
 export const PaginationSchema = z.object({
   page: z.number().int().min(1),
   pageSize: z.number().int().min(1),
@@ -146,19 +177,32 @@ export const ReleaseSummaryItemSchema = z.object({
 });
 
 /**
- * Inline citation attached to an overview page (#846). Each row maps a
- * character span in `OverviewPageItem.content` back to a release URL the
- * model cited via Anthropic's search_result blocks. Optional everywhere it
- * appears — pages generated before #846 lands have none, and consumers
- * should degrade gracefully.
+ * A source attached to an overview page (#846, reshaped #1934). Each row names
+ * a source the overview drew on — `sourceUrl` plus, when it resolved to an
+ * on-registry release, `releaseId` + a canonical `releaseWebUrl`. This is a
+ * source *list*, not span-anchored provenance: the old body char offsets +
+ * verbatim quote are removed. Optional everywhere it appears — consumers should
+ * degrade gracefully.
  */
 export const OverviewCitationSchema = z.object({
-  startIndex: z.number().int().min(0),
-  endIndex: z.number().int().min(0),
   sourceUrl: z.string(),
   title: z.string().nullable().optional(),
-  citedText: z.string(),
+  /** Best-effort link to the on-registry release this source maps to (resolved server-side). */
   releaseId: z.string().nullable().optional(),
+  /**
+   * Canonical web URL of the on-registry release page for this source, when
+   * `releaseId` resolved (#1934). The Sources footer links here (internal,
+   * crawlable) in preference to the external `sourceUrl`.
+   */
+  releaseWebUrl: z.string().nullable().optional(),
+  /**
+   * @deprecated Body char offsets / verbatim quote — removed with span-anchored
+   * citations (#1934). Kept optional for wire back-compat; no producer emits
+   * them and no consumer should read them.
+   */
+  startIndex: z.number().int().min(0).optional(),
+  endIndex: z.number().int().min(0).optional(),
+  citedText: z.string().optional(),
 });
 
 /**

package/src/schemas/well-known.test.ts

@@ -1,66 +1,163 @@
-import { describe, it, expect } from "bun:test";
-import { ReleasesJsonConfigSchema } from "./well-known.js";
+import { describe, expect, it } from "bun:test";
+import {
+  ReleasesJsonConfigSchema,
+  ReleasesJsonDomainSchema,
+  ReleasesJsonRepoSchema,
+} from "./well-known.js";
 
-describe("ReleasesJsonConfigSchema", () => {
-  it("accepts an empty object (no-op file)", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({}).success).toBe(true);
+const location = (n: number) => ({ url: `https://acme.com/releases/${n}` });
+
+describe("releases.json v2 schemas", () => {
+  it("accepts the minimal domain manifest", () => {
+    expect(
+      ReleasesJsonDomainSchema.parse({
+        version: 2,
+        releases: [{ url: "https://acme.com/updates", feed: "https://acme.com/updates.xml" }],
+      }),
+    ).toEqual({
+      version: 2,
+      releases: [{ url: "https://acme.com/updates", feed: "https://acme.com/updates.xml" }],
+    });
   });
 
-  it("accepts a full org-scope file", () => {
-    const r = ReleasesJsonConfigSchema.safeParse({
+  it("accepts the full domain shape with advisory taxonomy", () => {
+    const parsed = ReleasesJsonDomainSchema.parse({
       $schema: "https://releases.sh/schemas/releases.json",
-      version: 1,
+      version: 2,
       name: "Acme",
       description: "CI for teams.",
-      category: "developer-tools",
+      category: "future-category",
       avatar: "https://acme.com/logo.png",
-      tags: ["ci", "observability"],
+      tags: ["future-tag"],
       social: { twitter: "acmehq", github: "acme" },
-      notice: { message: "Docs moved", href: "https://acme.com/docs" },
+      products: [
+        {
+          name: "Acme Cloud",
+          slug: "acme-cloud",
+          kind: "future-kind",
+          category: "future-category",
+          description: "Managed CI runners.",
+          website: "https://acme.com/cloud",
+          docs: "https://docs.acme.com/cloud",
+          support: "https://acme.com/support",
+          social: { twitter: "acmecloud" },
+          archived: true,
+          releases: [{ github: "acme/cloud", canonical: true }],
+        },
+      ],
+      registries: {
+        "releases.sh": {
+          org: "org_abc123",
+          verification: "verification-token",
+          futureKey: true,
+        },
+        "example.com": { anything: "goes" },
+      },
     });
-    expect(r.success).toBe(true);
+
+    expect(parsed.products?.[0]?.kind).toBe("future-kind");
+    expect(parsed.registries?.["example.com"]).toEqual({ anything: "goes" });
   });
 
-  it("accepts a product-scope file", () => {
-    const r = ReleasesJsonConfigSchema.safeParse({
-      product: { name: "Acme Cloud", slug: "acme-cloud", category: "cloud", kind: "platform" },
-    });
-    expect(r.success).toBe(true);
+  it("accepts the repo variant including github self", () => {
+    expect(
+      ReleasesJsonRepoSchema.safeParse({
+        version: 2,
+        product: { name: "Acme Cloud", slug: "acme-cloud" },
+        releases: [{ github: "self", canonical: true }],
+        registries: { "releases.sh": { product: "prd_abc123" } },
+      }).success,
+    ).toBe(true);
   });
 
-  it("rejects a non-https avatar", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({ avatar: "http://acme.com/x.png" }).success).toBe(
-      false,
-    );
+  it("requires the version 2 literal with no v1 compatibility", () => {
+    expect(ReleasesJsonConfigSchema.safeParse({ releases: [location(1)] }).success).toBe(false);
+    expect(ReleasesJsonConfigSchema.safeParse({ version: 1 }).success).toBe(false);
+    expect(ReleasesJsonConfigSchema.safeParse({ version: 3 }).success).toBe(false);
   });
 
-  it("rejects a product with no name", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({ product: { slug: "x" } }).success).toBe(false);
+  it("requires at least one locator per release location", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, releases: [{ title: "Updates" }] }).success,
+    ).toBe(false);
   });
 
-  it("rejects an unknown product kind", () => {
+  it("allows github self only in repo files", () => {
     expect(
-      ReleasesJsonConfigSchema.safeParse({ product: { name: "Acme Cloud", kind: "saas" } }).success,
+      ReleasesJsonDomainSchema.safeParse({ version: 2, releases: [{ github: "self" }] }).success,
     ).toBe(false);
+    expect(
+      ReleasesJsonRepoSchema.safeParse({ version: 2, releases: [{ github: "self" }] }).success,
+    ).toBe(true);
   });
 
-  it("rejects an over-long notice message", () => {
-    const r = ReleasesJsonConfigSchema.safeParse({ notice: { message: "x".repeat(281) } });
-    expect(r.success).toBe(false);
+  it("enforces product and release-location caps", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: Array.from({ length: 25 }, (_, i) => ({ name: `Product ${i}` })),
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: [{ name: "Cloud", releases: Array.from({ length: 9 }, (_, i) => location(i)) }],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: Array.from({ length: 33 }, (_, i) => location(i)),
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: Array.from({ length: 25 }, (_, i) => location(i)),
+        products: [
+          { name: "Cloud", releases: Array.from({ length: 8 }, (_, i) => location(i + 25)) },
+        ],
+      }).success,
+    ).toBe(false);
   });
 
-  it("accepts an integer version", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({ version: 1, name: "Acme" }).success).toBe(true);
+  it("allows at most one canonical location per scope", () => {
+    const canonical = (n: number) => ({ ...location(n), canonical: true });
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        releases: [canonical(1), canonical(2)],
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        products: [{ name: "Cloud", releases: [canonical(1), canonical(2)] }],
+      }).success,
+    ).toBe(false);
   });
 
-  it("rejects a zero, negative, or non-integer version", () => {
-    expect(ReleasesJsonConfigSchema.safeParse({ version: 0 }).success).toBe(false);
-    expect(ReleasesJsonConfigSchema.safeParse({ version: -1 }).success).toBe(false);
-    expect(ReleasesJsonConfigSchema.safeParse({ version: 1.5 }).success).toBe(false);
+  it("rejects removed v1 identity fields", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, website: "https://acme.com" }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonDomainSchema.safeParse({ version: 2, notice: { message: "Moved" } }).success,
+    ).toBe(false);
   });
 
-  it("strips unknown top-level keys", () => {
-    const r = ReleasesJsonConfigSchema.parse({ name: "Acme", bogus: 1 });
-    expect("bogus" in r).toBe(false);
+  it("requires typed stable ids for the releases.sh registry", () => {
+    expect(
+      ReleasesJsonDomainSchema.safeParse({
+        version: 2,
+        registries: { "releases.sh": { org: "prd_wrong" } },
+      }).success,
+    ).toBe(false);
+    expect(
+      ReleasesJsonRepoSchema.safeParse({
+        version: 2,
+        registries: { "releases.sh": { product: "org_wrong" } },
+      }).success,
+    ).toBe(false);
   });
 });

package/src/schemas/well-known.ts

@@ -1,54 +1,207 @@
 import { z } from "zod";
-import { KIND_VALUES } from "@buildinternet/releases-core/kinds";
-import { NoticeSchema } from "./shared.js";
 
-/** A single social handle/URL. Bare handles allowed; URLs must be https. */
+const MAX_PRODUCTS = 24;
+const MAX_PRODUCT_RELEASES = 8;
+const MAX_FILE_RELEASES = 32;
+
+/** A single social handle/URL. Bare handles are intentionally accepted. */
 const SocialValueSchema = z.string().min(1).max(200);
+const SocialSchema = z.record(z.string().min(1).max(40), SocialValueSchema);
 
-/** Product-scope block: declares the hosting repo's source belongs to this product. */
-export const ReleasesJsonProductSchema = z
-  .object({
-    name: z.string().min(1).max(120),
-    slug: z.string().min(1).max(120).optional(),
-    description: z.string().max(2000).optional(),
-    // Accepted leniently as a string; resolved/validated against CATEGORIES at apply time.
-    category: z.string().min(1).max(120).optional(),
-    kind: z.enum(KIND_VALUES).optional(),
+const HttpsUrlSchema = z
+  .url()
+  .refine((url) => url.startsWith("https://"), "locator must be an https URL");
+
+const ReleaseLocationFields = {
+  url: HttpsUrlSchema.optional(),
+  feed: HttpsUrlSchema.optional(),
+  appstore: HttpsUrlSchema.optional(),
+  file: HttpsUrlSchema.optional(),
+  title: z.string().min(1).max(200).optional(),
+  canonical: z.boolean().optional(),
+};
+
+function hasLocator(value: {
+  url?: string;
+  feed?: string;
+  github?: string;
+  appstore?: string;
+  file?: string;
+}): boolean {
+  return Boolean(value.url || value.feed || value.github || value.appstore || value.file);
+}
+
+/** A domain manifest can name a concrete GitHub repository, but never `self`. */
+export const ReleasesJsonDomainReleaseSchema = z
+  .strictObject({
+    ...ReleaseLocationFields,
+    github: z
+      .string()
+      .regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, "github must be owner/repo")
+      .optional(),
+  })
+  .refine(hasLocator, "at least one release locator is required");
+
+/** A repo manifest additionally accepts `github: "self"`. */
+export const ReleasesJsonRepoReleaseSchema = z
+  .strictObject({
+    ...ReleaseLocationFields,
+    github: z
+      .union([
+        z.literal("self"),
+        z.string().regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, "github must be owner/repo"),
+      ])
+      .optional(),
   })
-  .strict();
+  .refine(hasLocator, "at least one release locator is required");
+
+function releasesArray<T extends z.ZodType>(item: T, max: number) {
+  return z
+    .array(item)
+    .max(max)
+    .refine(
+      (items) =>
+        items.filter((entry) => Boolean((entry as { canonical?: boolean }).canonical)).length <= 1,
+      "at most one canonical release location is allowed per scope",
+    );
+}
+
+const DomainProductReleasesSchema = releasesArray(
+  ReleasesJsonDomainReleaseSchema,
+  MAX_PRODUCT_RELEASES,
+);
+const RepoReleasesSchema = releasesArray(ReleasesJsonRepoReleaseSchema, MAX_FILE_RELEASES);
+const DomainReleasesSchema = releasesArray(ReleasesJsonDomainReleaseSchema, MAX_FILE_RELEASES);
 
 /**
- * One file name, two hosting scopes. Org-identity keys are honored only from a
- * domain `.well-known/releases.json`; `product` is honored only from a repo-root
- * file. The server enforces which keys it honors based on the host the file came
- * from — this schema only validates shape.
+ * Product declaration in a domain manifest. Taxonomy strings are deliberately
+ * lenient here; the reconciler resolves known values and ignores the rest.
  */
-export const ReleasesJsonConfigSchema = z
+export const ReleasesJsonProductSchema = z.strictObject({
+  name: z.string().min(1).max(120),
+  slug: z.string().min(1).max(120).optional(),
+  kind: z.string().min(1).max(120).optional(),
+  category: z.string().min(1).max(120).optional(),
+  description: z.string().max(2000).optional(),
+  website: z.url().optional(),
+  docs: z.url().optional(),
+  support: z.url().optional(),
+  social: SocialSchema.optional(),
+  archived: z.boolean().optional(),
+  releases: DomainProductReleasesSchema.optional(),
+});
+
+/** Repo-scope product binding. Slug is only a creation suggestion. */
+export const ReleasesJsonRepoProductSchema = z.strictObject({
+  name: z.string().min(1).max(120),
+  slug: z.string().min(1).max(120).optional(),
+});
+
+const ReleasesRegistrySchema = z
+  .object({
+    org: z
+      .string()
+      .regex(/^org_[A-Za-z0-9]+$/)
+      .optional(),
+    product: z
+      .string()
+      .regex(/^prd_[A-Za-z0-9]+$/)
+      .optional(),
+    verification: z.string().min(1).max(500).optional(),
+  })
+  .catchall(z.unknown());
+
+/** Registry-specific extensions are forward-compatible by design. */
+export const ReleasesJsonRegistriesSchema = z
   .object({
-    $schema: z.url().optional(),
-    // Manifest format version. Currently 1; optional — a missing value is read as
-    // v1. Bumped only on a breaking change to this file's shape, so a consumer can
-    // branch on it without fetching the JSON Schema. Lenient/fail-open: the
-    // reconciler ignores it entirely, so an unexpected value never fails the sync.
-    version: z.number().int().positive().max(1000).optional(),
-    // Org scope
+    "releases.sh": ReleasesRegistrySchema.optional(),
+  })
+  .catchall(z.unknown());
+
+/** Top-level fields shared by every manifest scope. */
+const BaseFields = {
+  $schema: z.url().optional(),
+  version: z.literal(2),
+  registries: ReleasesJsonRegistriesSchema.optional(),
+};
+
+const CommonFields = {
+  ...BaseFields,
+  releases: DomainReleasesSchema.optional(),
+};
+
+/** Domain-hosted variant: flat org identity plus product and release declarations. */
+export const ReleasesJsonDomainSchema = z
+  .strictObject({
+    ...CommonFields,
     name: z.string().min(1).max(120).optional(),
     description: z.string().max(2000).optional(),
     category: z.string().min(1).max(120).optional(),
-    avatar: z
-      .url()
-      .refine((u) => u.startsWith("https://"), "avatar must be an https URL")
-      .optional(),
+    avatar: HttpsUrlSchema.optional(),
     tags: z.array(z.string().min(1).max(60)).max(50).optional(),
-    social: z.record(z.string().min(1).max(40), SocialValueSchema).optional(),
-    notice: NoticeSchema.optional(),
-    // Source/product scope
-    product: ReleasesJsonProductSchema.optional(),
+    social: SocialSchema.optional(),
+    products: z.array(ReleasesJsonProductSchema).max(MAX_PRODUCTS).optional(),
   })
-  .strip();
+  .refine(
+    (manifest) =>
+      (manifest.releases?.length ?? 0) +
+        (manifest.products?.reduce((sum, product) => sum + (product.releases?.length ?? 0), 0) ??
+          0) <=
+      MAX_FILE_RELEASES,
+    `at most ${MAX_FILE_RELEASES} release locations are allowed per file`,
+  );
+
+/** Repo-root variant: product binding plus repo-scoped release declarations. */
+export const ReleasesJsonRepoSchema = z.strictObject({
+  ...BaseFields,
+  product: ReleasesJsonRepoProductSchema.optional(),
+  releases: RepoReleasesSchema.optional(),
+});
+
+/** Public schema accepts either hosting scope; reconcilers use the scoped schema. */
+export const ReleasesJsonConfigSchema = z.union([ReleasesJsonDomainSchema, ReleasesJsonRepoSchema]);
 
 export type ReleasesJsonConfig = z.infer<typeof ReleasesJsonConfigSchema>;
+export type ReleasesJsonDomain = z.infer<typeof ReleasesJsonDomainSchema>;
+export type ReleasesJsonRepo = z.infer<typeof ReleasesJsonRepoSchema>;
 export type ReleasesJsonProduct = z.infer<typeof ReleasesJsonProductSchema>;
+export type ReleasesJsonDomainRelease = z.infer<typeof ReleasesJsonDomainReleaseSchema>;
+export type ReleasesJsonRepoRelease = z.infer<typeof ReleasesJsonRepoReleaseSchema>;
+
+/**
+ * Body for `POST /v1/orgs/stub` — curator-authored stub org (#1947). Mirrors
+ * the domain-manifest identity + product + locator shape (so a curator can hand
+ * the same declaration a manifest would carry), minus manifest-transport fields
+ * (`version`/`$schema`/`registries`) and plus the registry-identity fields a
+ * stub org needs to be resolvable (`slug`/`domain`). Locators are optional — an
+ * identity-only stub (locations TBD) is valid. `category`/taxonomy strings stay
+ * lenient; the route resolves them and ignores the rest, same as the reconciler.
+ */
+export const CreateStubOrgBodySchema = z.strictObject({
+  name: z.string().min(1).max(120),
+  slug: z.string().min(1).max(120).optional(),
+  domain: z.string().min(1).max(255).optional(),
+  description: z.string().max(2000).optional(),
+  category: z.string().min(1).max(120).optional(),
+  avatar: HttpsUrlSchema.optional(),
+  tags: z.array(z.string().min(1).max(60)).max(50).optional(),
+  social: SocialSchema.optional(),
+  products: z.array(ReleasesJsonProductSchema).max(MAX_PRODUCTS).optional(),
+  releases: DomainReleasesSchema.optional(),
+});
+
+export type CreateStubOrgBody = z.infer<typeof CreateStubOrgBodySchema>;
+
+/**
+ * Body for `POST /v1/orgs/stub-from-domain` (#1947) — the unlisted-domain path.
+ * The worker fetches https://{domain}/.well-known/releases.json and, if valid
+ * and the domain has no org yet, creates a stub org + declared locators.
+ */
+export const StubFromDomainBodySchema = z.strictObject({
+  domain: z.string().min(1).max(255),
+});
+
+export type StubFromDomainBody = z.infer<typeof StubFromDomainBodySchema>;
 
 /** Response shape of POST /v1/orgs/:slug/sync-well-known. */
 export const SyncWellKnownResponseSchema = z.object({