feat: add tenant semantic documentation lifecycle

webui/src/api/docs.ts

@@ -275,3 +275,118 @@ export function fetchDocsSource(
     `/api/v1/docs/sources/${encodeURIComponent(sourceId)}${query ? `?${query}` : ""}`
   );
 }
+
+export type SemanticSubjectReference = {
+  module_id: string;
+  tenant_id: string;
+  subject_kind: string;
+  subject_id: string;
+  anchor?: { kind: string; id: string } | null;
+  observed_revision?: string | null;
+  observed_fingerprint?: string | null;
+};
+
+export type SemanticSubjectDescriptor = {
+  reference: SemanticSubjectReference;
+  labels: Record<string, string>;
+  descriptions: Record<string, string>;
+  route?: string | null;
+  route_anchor?: string | null;
+};
+
+export type SemanticContent = {
+  title: string;
+  summary: string;
+  body: string;
+  meaning: string;
+  intended_use: string;
+  non_intended_use: string;
+  examples: string[];
+  owner_account_id: string | null;
+  steward_account_id: string | null;
+  audience: string[];
+  classification: "internal" | "restricted";
+  links: Array<{ label: string; href: string }>;
+};
+
+export type SemanticEntry = {
+  id: string;
+  subject: SemanticSubjectReference;
+  subject_resolution: {
+    availability: "available" | "changed" | "superseded" | "missing" | "temporarily_unavailable";
+    reason_code?: string | null;
+  };
+  locale: string;
+  requested_locale: string;
+  locale_fallback: boolean;
+  lifecycle_state: "draft" | "published" | "superseded" | "retired";
+  pending_draft: boolean;
+  current_revision: number;
+  published_revision?: number | null;
+  content: SemanticContent;
+  content_redacted: boolean;
+  updated_at: string;
+};
+
+export async function fetchSemanticSubjects(
+  settings: ApiSettings,
+  query = ""
+): Promise<SemanticSubjectDescriptor[]> {
+  const params = new URLSearchParams({ query });
+  const response = await apiFetch<{ providers: Array<{ subjects: SemanticSubjectDescriptor[] }> }>(
+    settings,
+    `/api/v1/docs/semantic/subjects?${params}`
+  );
+  return response.providers.flatMap((provider) => provider.subjects);
+}
+
+export async function fetchSemanticEntries(
+  settings: ApiSettings,
+  locale: string,
+  includeDrafts = true
+): Promise<SemanticEntry[]> {
+  const params = new URLSearchParams({ locale, include_drafts: String(includeDrafts) });
+  const response = await apiFetch<{ items: SemanticEntry[] }>(
+    settings,
+    `/api/v1/docs/semantic/entries?${params}`
+  );
+  return response.items;
+}
+
+export function createSemanticEntry(
+  settings: ApiSettings,
+  payload: { subject: SemanticSubjectReference; locale: string; content: SemanticContent; change_reason: string }
+): Promise<SemanticEntry> {
+  return apiFetch(settings, "/api/v1/docs/semantic/entries", {
+    method: "POST",
+    body: JSON.stringify(payload)
+  });
+}
+
+export function updateSemanticEntry(
+  settings: ApiSettings,
+  entryId: string,
+  payload: { expected_revision: number; content: SemanticContent; change_reason: string }
+): Promise<SemanticEntry> {
+  return apiFetch(settings, `/api/v1/docs/semantic/entries/${encodeURIComponent(entryId)}`, {
+    method: "PUT",
+    body: JSON.stringify(payload)
+  });
+}
+
+export function transitionSemanticEntry(
+  settings: ApiSettings,
+  entryId: string,
+  transition: "publish" | "retire",
+  expectedRevision: number,
+  changeReason: string
+): Promise<SemanticEntry> {
+  return apiFetch(
+    settings,
+    `/api/v1/docs/semantic/entries/${encodeURIComponent(entryId)}/${transition}`,
+    {
+      method: "POST",
+      body: JSON.stringify({ expected_revision: expectedRevision, change_reason: changeReason })
+    }
+  );
+}