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
+207
View File
@@ -0,0 +1,207 @@
/**
* src/features/feast-adapter.ts
* ==============================
* Feature capability contract + Feast adapter (Master-DoD §10 Feature
* capability: Feature definitions, Feast adapter, offline/online,
* point-in-time correctness, materialization, versioning, feature lineage).
*
* What is REAL here vs. contract-only — stated plainly (§56):
* - Feature-view registry with versioning: REAL (in-process registry,
* versioned like QualityService rules).
* - get-online-features: REAL HTTP adapter against Feast's feature server
* (`POST /get-online-features`, Feast's documented REST contract).
* Contract-tested against a recording double; needs a live Feast for
* INTEGRATION_TESTED.
* - materialize / get-historical (offline, point-in-time): DELEGATION
* CONTRACTS ONLY — Feast materialization and offline retrieval are
* Python-side operations; 0pt submits N0D jobs ("0pt.features.materialize",
* "0pt.features.get_historical") for 0pt-motor to execute. This adapter
* never fakes a result for them.
*/
import { SiaxError, siaxErrorCodeForUpstreamStatus } from "../platform/errors";
import type { N0dClient, N0dJob } from "../clients/n0d-client";
/** A versioned 0pt feature-view definition (maps to a Feast FeatureView). */
export interface FeatureViewDefinition {
feature_view: string;
tenant_id: string;
project_id: string;
/** Entity join keys, e.g. ["org_nr"]. */
entities: string[];
features: { name: string; dtype: "int64" | "float64" | "string" | "bool" | "timestamp" }[];
/** Source dataset ref this view materializes from (canonical 0pt ref). */
source_dataset_ref: string;
ttl_hours?: number;
version: number;
created_at: string;
}
export type RegisterFeatureViewInput = Omit<FeatureViewDefinition, "version" | "created_at">;
export interface OnlineFeaturesRequest {
tenant_id: string;
feature_view: string;
features: string[];
/** Entity rows, e.g. [{ org_nr: "5560360793" }]. */
entities: Record<string, (string | number)[]>;
}
export interface OnlineFeaturesResult {
feature_names: string[];
results: { values: unknown[]; statuses: string[] }[];
}
export class FeatureService {
private readonly views = new Map<string, FeatureViewDefinition>();
private readonly history = new Map<string, FeatureViewDefinition[]>();
constructor(
private readonly opts: {
/** Feast feature-server base URL (online path). */
feastServerUrl?: string;
n0dClient?: N0dClient;
timeoutMs?: number;
} = {}
) {}
// -----------------------------------------------------------------------
// Registry (versioned)
// -----------------------------------------------------------------------
registerFeatureView(input: RegisterFeatureViewInput): FeatureViewDefinition {
const key = `${input.tenant_id}:${input.feature_view}`;
const current = this.views.get(key);
if (current) {
const hist = this.history.get(key) ?? [];
hist.push(current);
this.history.set(key, hist);
}
const def: FeatureViewDefinition = {
...input,
version: (current?.version ?? 0) + 1,
created_at: new Date().toISOString(),
};
this.views.set(key, def);
return def;
}
getFeatureView(tenantId: string, featureView: string): FeatureViewDefinition {
const def = this.views.get(`${tenantId}:${featureView}`);
if (!def) throw new SiaxError("NOT_FOUND", "0pt.features", `feature view ${featureView} not found`);
return def;
}
getFeatureViewVersions(tenantId: string, featureView: string): FeatureViewDefinition[] {
const current = this.getFeatureView(tenantId, featureView);
return [...(this.history.get(`${tenantId}:${featureView}`) ?? []), current];
}
// -----------------------------------------------------------------------
// Online path — REAL Feast feature-server adapter
// -----------------------------------------------------------------------
async getOnlineFeatures(req: OnlineFeaturesRequest): Promise<OnlineFeaturesResult> {
this.getFeatureView(req.tenant_id, req.feature_view); // tenant + existence gate
if (!this.opts.feastServerUrl) {
throw new SiaxError(
"DEPENDENCY_UNAVAILABLE",
"feast",
"no Feast feature server configured (FEAST_SERVER_URL)"
);
}
let res: Response;
try {
res = await fetch(`${this.opts.feastServerUrl.replace(/\/+$/, "")}/get-online-features`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
// Feast REST contract: features as "view:feature" refs.
features: req.features.map((f) => `${req.feature_view}:${f}`),
entities: req.entities,
}),
signal: AbortSignal.timeout(this.opts.timeoutMs ?? 10_000),
});
} catch (cause) {
throw new SiaxError("DEPENDENCY_UNAVAILABLE", "feast", "feast feature server unreachable", { cause });
}
if (!res.ok) {
throw new SiaxError(
siaxErrorCodeForUpstreamStatus(res.status),
"feast",
`get-online-features → HTTP ${res.status}`
);
}
const body = (await res.json()) as {
metadata?: { feature_names?: string[] };
results?: { values: unknown[]; statuses: string[] }[];
};
return {
feature_names: body.metadata?.feature_names ?? [],
results: body.results ?? [],
};
}
// -----------------------------------------------------------------------
// Offline paths — N0D delegation contracts (never faked locally)
// -----------------------------------------------------------------------
async materialize(input: {
tenant_id: string;
project_id: string;
feature_view: string;
start_time: string;
end_time: string;
correlation_id?: string;
}): Promise<N0dJob> {
const def = this.getFeatureView(input.tenant_id, input.feature_view);
return this.requireN0d().createJob({
tenant_id: input.tenant_id,
project_id: input.project_id,
job_type: "0pt.features.materialize",
capability_id: "0pt.features.materialize.v1",
requested_by_app_id: "0pt",
requested_by_actor_id: "svc_0pt",
output_artifact_type: "feature_materialization",
requires_backbone: false,
requires_gpu: false,
required_node_roles: ["compute_general"],
resource_profile: "standard",
risk_level: "L2",
correlation_id: input.correlation_id,
idempotency_key: `feat-mat:${input.feature_view}@${def.version}:${input.start_time}:${input.end_time}`,
});
}
/** Point-in-time correct historical retrieval — Feast offline via 0pt-motor. */
async getHistorical(input: {
tenant_id: string;
project_id: string;
feature_view: string;
features: string[];
/** ST0RE artifact ref of the entity dataframe (with event timestamps). */
entity_df_artifact_ref: string;
correlation_id?: string;
}): Promise<N0dJob> {
this.getFeatureView(input.tenant_id, input.feature_view);
return this.requireN0d().createJob({
tenant_id: input.tenant_id,
project_id: input.project_id,
job_type: "0pt.features.get_historical",
capability_id: "0pt.features.get_historical.v1",
requested_by_app_id: "0pt",
requested_by_actor_id: "svc_0pt",
input_artifact_ids: [input.entity_df_artifact_ref],
output_artifact_type: "feature_historical_result",
requires_backbone: false,
requires_gpu: false,
required_node_roles: ["compute_general"],
resource_profile: "standard",
risk_level: "L2",
correlation_id: input.correlation_id,
});
}
private requireN0d(): N0dClient {
if (!this.opts.n0dClient) {
throw new SiaxError("DEPENDENCY_UNAVAILABLE", "n0d", "no N0D client configured for feature jobs");
}
return this.opts.n0dClient;
}
}