fix(recovery): restore source removed by production documentation merge

This commit is contained in:
2026-11-10 03:42:10 +01:00
parent 585bdd4b44
commit 3d2fc6f913
957 changed files with 115754 additions and 0 deletions
+134
View File
@@ -0,0 +1,134 @@
/**
* src/metadata/openmetadata-adapter.ts
* =====================================
* OpenMetadata PROJECTION adapter (Master-DoD §10 Metadata: "OpenMetadata
* som projection (inte canonical)").
*
* Doctrine, stated plainly:
* - 0pt's registries (DatasetService/DatasetVersionService/SourceRegistry)
* are CANONICAL. OpenMetadata is a rebuildable projection for humans —
* deleting the OpenMetadata instance loses NOTHING canonical.
* - `projectAll()` therefore exists and is the recovery path (§42).
*
* Wire contract: OpenMetadata 1.x REST — PUT /api/v1/tables (createOrUpdate
* semantics) with a bearer bot token (OM's standard ingestion-bot auth).
* The subset used (fullyQualifiedName via service/database/schema hierarchy,
* columns, description, tags) is stable across OM 1.x.
*
* STATUS HONESTY: adapter + projection service are real code with contract
* tests against a recording double. NOT yet integration-tested against a
* live OpenMetadata (no local container in this pass) — classified
* IMPLEMENTED, not INTEGRATION_TESTED, in STATUS.md.
*/
import { SiaxError, siaxErrorCodeForUpstreamStatus } from "../platform/errors";
import type { Dataset } from "../types/dataset";
import type { DatasetVersion } from "../services/dataset-version-service";
export interface OpenMetadataAdapterOptions {
baseUrl: string;
/** OM bot JWT. Comes from env/secret ref — never hardcoded. */
token?: string;
timeoutMs?: number;
}
/** The projected table entity (OM createOrUpdate subset). */
export interface OmTableUpsert {
name: string;
databaseSchema: string;
description?: string;
columns: { name: string; dataType: string; description?: string }[];
tags?: { tagFQN: string }[];
}
export interface MetadataProjectionResult {
projected: number;
failures: { dataset_id: string; error: string }[];
}
export class OpenMetadataAdapter {
private readonly baseUrl: string;
private readonly token?: string;
private readonly timeoutMs: number;
constructor(opts: OpenMetadataAdapterOptions) {
this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
this.token = opts.token;
this.timeoutMs = opts.timeoutMs ?? 15_000;
}
async upsertTable(table: OmTableUpsert): Promise<void> {
const headers: Record<string, string> = { "Content-Type": "application/json" };
if (this.token) headers["Authorization"] = `Bearer ${this.token}`;
let res: Response;
try {
res = await fetch(`${this.baseUrl}/api/v1/tables`, {
method: "PUT",
headers,
body: JSON.stringify(table),
signal: AbortSignal.timeout(this.timeoutMs),
});
} catch (cause) {
throw new SiaxError("DEPENDENCY_UNAVAILABLE", "openmetadata", "PUT /api/v1/tables unreachable", { cause });
}
if (!res.ok) {
throw new SiaxError(
siaxErrorCodeForUpstreamStatus(res.status),
"openmetadata",
`PUT /api/v1/tables → HTTP ${res.status}`
);
}
}
}
/**
* Projects 0pt's canonical dataset registry into OpenMetadata. Pure mapping +
* adapter calls; failures are collected per dataset, never silently dropped.
*/
export class MetadataProjectionService {
constructor(
private readonly adapter: OpenMetadataAdapter,
/** OM schema FQN the projection writes under, e.g. "0pt.default.datasets". */
private readonly schemaFqn: string = "0pt.default.datasets"
) {}
toTableUpsert(dataset: Dataset, latestVersion?: DatasetVersion): OmTableUpsert {
return {
name: dataset.dataset_id,
databaseSchema: this.schemaFqn,
description:
`${dataset.name} — PROJECTION of canonical 0pt dataset registry entry ` +
`0pt:dataset:${dataset.dataset_id}` +
(latestVersion ? ` (latest version ${latestVersion.version}, schema ${latestVersion.schema_version})` : "") +
`. Canonical truth lives in 0pt; this record is rebuildable.`,
columns: [
{ name: "dataset_id", dataType: "STRING", description: "Canonical 0pt dataset id" },
{ name: "tenant_id", dataType: "STRING", description: "Owning tenant" },
{ name: "dataset_type", dataType: "STRING", description: dataset.dataset_type },
{ name: "status", dataType: "STRING", description: dataset.status },
],
tags: [{ tagFQN: "0ptProjection.canonical-elsewhere" }],
};
}
async projectDataset(dataset: Dataset, latestVersion?: DatasetVersion): Promise<void> {
await this.adapter.upsertTable(this.toTableUpsert(dataset, latestVersion));
}
/** The §42 recovery path: re-project everything from canonical registries. */
async projectAll(
datasets: Dataset[],
latestVersions: Map<string, DatasetVersion>
): Promise<MetadataProjectionResult> {
const failures: { dataset_id: string; error: string }[] = [];
let projected = 0;
for (const ds of datasets) {
try {
await this.projectDataset(ds, latestVersions.get(ds.dataset_id));
projected++;
} catch (err) {
failures.push({ dataset_id: ds.dataset_id, error: err instanceof Error ? err.message : String(err) });
}
}
return { projected, failures };
}
}