@netgreener/runtime 0.1.0

package/dist/contract/observationProjection.js

@@ -0,0 +1,29 @@
+/**
+ * Observation semantic-projection helpers (ADR 0008 D2 twin).
+ *
+ * Additive helper for golden parity. Does not change upload/emit paths.
+ */
+import { createHash } from 'node:crypto';
+export function projectValue(value) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        const out = {};
+        for (const key of Object.keys(obj).sort()) {
+            if (obj[key] !== null && obj[key] !== undefined) {
+                out[key] = projectValue(obj[key]);
+            }
+        }
+        return out;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => projectValue(item));
+    }
+    return value;
+}
+export function projectionBytes(document) {
+    const projected = projectValue(document);
+    return Buffer.from(JSON.stringify(projected), 'utf8');
+}
+export function projectionDigest(document) {
+    return 'sha256:' + createHash('sha256').update(projectionBytes(document)).digest('hex');
+}

package/dist/contract/validate.d.ts

@@ -0,0 +1,20 @@
+import type { ExternalApiV0, MeasurementProvenance, RuntimeSessionMetadata, ServiceRuntimeV0 } from '../types.js';
+export type ContractIssue = {
+    path: string;
+    message: string;
+};
+export type ContractResult = {
+    ok: boolean;
+    issues: ContractIssue[];
+};
+/** Validate the legacy Python-compatible v0 scaffold. MP0 remains the authority. */
+export declare function validateServiceRuntimeV0(value: unknown, path?: string): ContractResult;
+/** Validate external_api_v0 including optional by_model buckets. */
+export declare function validateExternalApiV0(value: unknown, path?: string): ContractResult;
+export declare function validateMeasurementProvenance(value: unknown, path?: string): ContractResult;
+/**
+ * Validate a session_metadata fragment Node will upload.
+ * Requires at least service_runtime_v0 or external_api_v0.
+ */
+export declare function validateRuntimeSessionMetadata(value: unknown): ContractResult;
+export type { ExternalApiV0, MeasurementProvenance, RuntimeSessionMetadata, ServiceRuntimeV0, };

package/dist/contract/validate.js

@@ -0,0 +1,227 @@
+function issue(path, message) {
+    return { path, message };
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNumber(obj, key, path, issues, requirements = {}) {
+    const value = obj[key];
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        issues.push(issue(`${path}.${key}`, 'expected number'));
+        return;
+    }
+    if (requirements.nonNegative && value < 0) {
+        issues.push(issue(`${path}.${key}`, 'expected non-negative number'));
+    }
+    if (requirements.integer && !Number.isSafeInteger(value)) {
+        issues.push(issue(`${path}.${key}`, 'expected safe integer'));
+    }
+    if (requirements.maximum !== undefined && value > requirements.maximum) {
+        issues.push(issue(`${path}.${key}`, `expected number at most ${requirements.maximum}`));
+    }
+}
+function optionalNumber(obj, key, path, issues, requirements = {}) {
+    if (obj[key] !== undefined) {
+        requireNumber(obj, key, path, issues, requirements);
+    }
+}
+function errorsDoNotExceedCalls(obj, path, issues) {
+    if (typeof obj.calls === 'number' &&
+        Number.isFinite(obj.calls) &&
+        typeof obj.errors === 'number' &&
+        Number.isFinite(obj.errors) &&
+        obj.errors > obj.calls) {
+        issues.push(issue(`${path}.errors`, 'must not exceed calls'));
+    }
+}
+function requireString(obj, key, path, issues) {
+    if (typeof obj[key] !== 'string' || !obj[key].trim()) {
+        issues.push(issue(`${path}.${key}`, 'expected non-empty string'));
+    }
+}
+/** Validate the legacy Python-compatible v0 scaffold. MP0 remains the authority. */
+export function validateServiceRuntimeV0(value, path = 'service_runtime_v0') {
+    const issues = [];
+    if (!isObject(value)) {
+        return { ok: false, issues: [issue(path, 'expected object')] };
+    }
+    requireString(value, 'collector', path, issues);
+    requireNumber(value, 'window_seconds', path, issues, { nonNegative: true });
+    requireString(value, 'attribution', path, issues);
+    requireString(value, 'accuracy', path, issues);
+    if (!Array.isArray(value.units)) {
+        issues.push(issue(`${path}.units`, 'expected array'));
+    }
+    else {
+        value.units.forEach((unit, index) => {
+            const up = `${path}.units[${index}]`;
+            if (!isObject(unit)) {
+                issues.push(issue(up, 'expected object'));
+                return;
+            }
+            requireString(unit, 'service_unit', up, issues);
+            requireString(unit, 'unit_type', up, issues);
+            requireNumber(unit, 'calls', up, issues, { nonNegative: true, integer: true });
+            requireNumber(unit, 'errors', up, issues, { nonNegative: true, integer: true });
+            errorsDoNotExceedCalls(unit, up, issues);
+            requireNumber(unit, 'cpu_seconds_total', up, issues, { nonNegative: true });
+            requireNumber(unit, 'energy_kwh', up, issues, { nonNegative: true });
+            requireNumber(unit, 'carbon_g', up, issues, { nonNegative: true });
+            optionalNumber(unit, 'peak_rss_kb_max', up, issues, { nonNegative: true });
+            optionalNumber(unit, 'cpu_percent_hours', up, issues, { nonNegative: true });
+            optionalNumber(unit, 'ram_gb_hours', up, issues, { nonNegative: true });
+            optionalNumber(unit, 'process_gpu_hours', up, issues, { nonNegative: true });
+            if (!isObject(unit.duration_ms)) {
+                issues.push(issue(`${up}.duration_ms`, 'expected object'));
+            }
+            else {
+                requireNumber(unit.duration_ms, 'avg', `${up}.duration_ms`, issues, {
+                    nonNegative: true,
+                });
+                requireNumber(unit.duration_ms, 'max', `${up}.duration_ms`, issues, {
+                    nonNegative: true,
+                });
+            }
+        });
+    }
+    if (value.allocation_reconciliation_v0 !== undefined) {
+        const reconciliationPath = `${path}.allocation_reconciliation_v0`;
+        if (!isObject(value.allocation_reconciliation_v0)) {
+            issues.push(issue(reconciliationPath, 'expected object'));
+        }
+        else {
+            const reconciliation = value.allocation_reconciliation_v0;
+            requireNumber(reconciliation, 'schema_version', reconciliationPath, issues, {
+                nonNegative: true,
+                integer: true,
+            });
+            requireNumber(reconciliation, 'window_energy_kwh', reconciliationPath, issues, {
+                nonNegative: true,
+            });
+            requireNumber(reconciliation, 'allocated_energy_kwh', reconciliationPath, issues, {
+                nonNegative: true,
+            });
+            requireNumber(reconciliation, 'residual_energy_kwh', reconciliationPath, issues);
+            requireNumber(reconciliation, 'tolerance_kwh', reconciliationPath, issues, {
+                nonNegative: true,
+            });
+            if (reconciliation.endpoint_capture_coverage !== null &&
+                reconciliation.endpoint_capture_coverage !== undefined) {
+                requireNumber(reconciliation, 'endpoint_capture_coverage', reconciliationPath, issues, {
+                    nonNegative: true,
+                    maximum: 1,
+                });
+            }
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
+/** Validate external_api_v0 including optional by_model buckets. */
+export function validateExternalApiV0(value, path = 'external_api_v0') {
+    const issues = [];
+    if (!isObject(value)) {
+        return { ok: false, issues: [issue(path, 'expected object')] };
+    }
+    requireString(value, 'collector', path, issues);
+    if (!Array.isArray(value.providers)) {
+        issues.push(issue(`${path}.providers`, 'expected array'));
+        return { ok: false, issues };
+    }
+    value.providers.forEach((provider, index) => {
+        const pp = `${path}.providers[${index}]`;
+        if (!isObject(provider)) {
+            issues.push(issue(pp, 'expected object'));
+            return;
+        }
+        requireString(provider, 'provider_key', pp, issues);
+        requireNumber(provider, 'calls', pp, issues, { nonNegative: true, integer: true });
+        requireNumber(provider, 'errors', pp, issues, { nonNegative: true, integer: true });
+        errorsDoNotExceedCalls(provider, pp, issues);
+        optionalNumber(provider, 'duration_ms_avg', pp, issues, { nonNegative: true });
+        optionalNumber(provider, 'input_tokens', pp, issues, { nonNegative: true, integer: true });
+        optionalNumber(provider, 'output_tokens', pp, issues, { nonNegative: true, integer: true });
+        optionalNumber(provider, 'total_tokens', pp, issues, { nonNegative: true, integer: true });
+        if (provider.by_model !== undefined) {
+            if (!Array.isArray(provider.by_model)) {
+                issues.push(issue(`${pp}.by_model`, 'expected array'));
+            }
+            else {
+                provider.by_model.forEach((row, mi) => {
+                    const mp = `${pp}.by_model[${mi}]`;
+                    if (!isObject(row)) {
+                        issues.push(issue(mp, 'expected object'));
+                        return;
+                    }
+                    requireString(row, 'model', mp, issues);
+                    requireNumber(row, 'calls', mp, issues, { nonNegative: true, integer: true });
+                    requireNumber(row, 'errors', mp, issues, { nonNegative: true, integer: true });
+                    errorsDoNotExceedCalls(row, mp, issues);
+                    optionalNumber(row, 'input_tokens', mp, issues, { nonNegative: true, integer: true });
+                    optionalNumber(row, 'output_tokens', mp, issues, { nonNegative: true, integer: true });
+                    optionalNumber(row, 'total_tokens', mp, issues, { nonNegative: true, integer: true });
+                });
+            }
+        }
+    });
+    return { ok: issues.length === 0, issues };
+}
+export function validateMeasurementProvenance(value, path = 'measurement_provenance') {
+    const issues = [];
+    if (!isObject(value)) {
+        return { ok: false, issues: [issue(path, 'expected object')] };
+    }
+    const carbonFactor = value.carbon_factor;
+    if (carbonFactor !== undefined) {
+        if (!isObject(carbonFactor)) {
+            issues.push(issue(`${path}.carbon_factor`, 'expected object'));
+        }
+        else if (carbonFactor.value !== null) {
+            requireNumber(carbonFactor, 'value', `${path}.carbon_factor`, issues, {
+                nonNegative: true,
+            });
+        }
+    }
+    const grades = value.evidence_grades;
+    if (grades !== undefined) {
+        if (!isObject(grades)) {
+            issues.push(issue(`${path}.evidence_grades`, 'expected object'));
+        }
+        else {
+            requireNumber(grades, 'schema_version', `${path}.evidence_grades`, issues, {
+                nonNegative: true,
+                integer: true,
+            });
+            requireString(grades, 'policy_version', `${path}.evidence_grades`, issues);
+            requireString(grades, 'combined_floor_grade', `${path}.evidence_grades`, issues);
+            if (!isObject(grades.metrics)) {
+                issues.push(issue(`${path}.evidence_grades.metrics`, 'expected object'));
+            }
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}
+/**
+ * Validate a session_metadata fragment Node will upload.
+ * Requires at least service_runtime_v0 or external_api_v0.
+ */
+export function validateRuntimeSessionMetadata(value) {
+    const issues = [];
+    if (!isObject(value)) {
+        return { ok: false, issues: [issue('session_metadata', 'expected object')] };
+    }
+    const hasRuntime = value.service_runtime_v0 !== undefined;
+    const hasExternal = value.external_api_v0 !== undefined;
+    if (!hasRuntime && !hasExternal) {
+        issues.push(issue('session_metadata', 'expected service_runtime_v0 and/or external_api_v0'));
+    }
+    if (hasRuntime) {
+        issues.push(...validateServiceRuntimeV0(value.service_runtime_v0).issues);
+    }
+    if (hasExternal) {
+        issues.push(...validateExternalApiV0(value.external_api_v0).issues);
+    }
+    if (value.measurement_provenance !== undefined) {
+        issues.push(...validateMeasurementProvenance(value.measurement_provenance).issues);
+    }
+    return { ok: issues.length === 0, issues };
+}

package/dist/dogfood/mp3WorkerGates.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MP3 worker-gate helpers (BullMQ concurrency + restart; process restart).
+ *
+ * Pure assertions over flushed session_metadata — no Redis required in unit tests.
+ * Does not claim production support or change export defaults.
+ */
+export type Mp3WorkerGateFlush = {
+    sessionMetadata?: {
+        service_runtime_v0?: {
+            collector?: string;
+            units?: Array<{
+                service_unit?: string;
+                calls?: number;
+                unit_type?: string;
+            }>;
+            by_tenant?: Record<string, unknown>;
+        };
+    } | null;
+    /** Number of jobs the harness observed as completed. */
+    completedJobs: number;
+    /** Expected minimum completed jobs for this phase. */
+    minCompletedJobs: number;
+    /** Optional tenant key that must appear when tenants are configured. */
+    expectedTenant?: string;
+    /** Optional task unit name (e.g. task:analyze_document). */
+    expectedTaskUnit?: string;
+    phase: 'concurrency' | 'restart' | 'process_restart';
+    /** Expected collector metadata (default bullmq_worker). */
+    expectedCollector?: string;
+};
+export type Mp3WorkerGateResult = {
+    ok: true;
+    phase: string;
+} | {
+    ok: false;
+    phase: string;
+    reason: string;
+};
+/**
+ * Concurrency phase: enough jobs completed and expected collector metadata present.
+ * When expectedTaskUnit is set, recorded calls must be ≥ 1 (unit must exist).
+ */
+export declare function assertMp3ConcurrencyGate(input: Mp3WorkerGateFlush): Mp3WorkerGateResult;
+/**
+ * Restart phase: a second worker generation completed jobs and still emits
+ * expected collector metadata (proves wrap survives worker.close → new Worker).
+ */
+export declare function assertMp3RestartGate(input: Mp3WorkerGateFlush): Mp3WorkerGateResult;
+/**
+ * Process/cron restart: after `_resetRuntimeForTests` + new `startProcessRuntime`,
+ * flush still emits ``node_process`` with tenant/task samples.
+ */
+export declare function assertMp3ProcessRestartGate(input: Mp3WorkerGateFlush): Mp3WorkerGateResult;
+export declare function formatMp3GateFailure(result: Mp3WorkerGateResult): string;

package/dist/dogfood/mp3WorkerGates.js

@@ -0,0 +1,86 @@
+/**
+ * MP3 worker-gate helpers (BullMQ concurrency + restart; process restart).
+ *
+ * Pure assertions over flushed session_metadata — no Redis required in unit tests.
+ * Does not claim production support or change export defaults.
+ */
+function taskUnitCalls(meta, serviceUnit) {
+    const units = meta.service_runtime_v0?.units || [];
+    const hit = units.find((u) => u.service_unit === serviceUnit);
+    return Number(hit?.calls || 0);
+}
+/**
+ * Concurrency phase: enough jobs completed and expected collector metadata present.
+ * When expectedTaskUnit is set, recorded calls must be ≥ 1 (unit must exist).
+ */
+export function assertMp3ConcurrencyGate(input) {
+    const phase = input.phase || 'concurrency';
+    const expectedCollector = input.expectedCollector || 'bullmq_worker';
+    if (input.completedJobs < input.minCompletedJobs) {
+        return {
+            ok: false,
+            phase,
+            reason: `completedJobs=${input.completedJobs} < minCompletedJobs=${input.minCompletedJobs}`,
+        };
+    }
+    const meta = input.sessionMetadata;
+    if (!meta?.service_runtime_v0) {
+        return { ok: false, phase, reason: 'missing service_runtime_v0 after concurrency flush' };
+    }
+    const collector = meta.service_runtime_v0.collector;
+    if (collector !== expectedCollector) {
+        return {
+            ok: false,
+            phase,
+            reason: `collector=${collector ?? '(none)'} expected ${expectedCollector}`,
+        };
+    }
+    if (input.expectedTaskUnit) {
+        const calls = taskUnitCalls(meta, input.expectedTaskUnit);
+        if (calls < 1) {
+            return {
+                ok: false,
+                phase,
+                reason: `missing task unit ${input.expectedTaskUnit} (calls=${calls})`,
+            };
+        }
+    }
+    if (input.expectedTenant) {
+        const tenants = meta.service_runtime_v0.by_tenant || {};
+        if (!(input.expectedTenant in tenants)) {
+            return {
+                ok: false,
+                phase,
+                reason: `missing by_tenant.${input.expectedTenant}`,
+            };
+        }
+    }
+    return { ok: true, phase };
+}
+/**
+ * Restart phase: a second worker generation completed jobs and still emits
+ * expected collector metadata (proves wrap survives worker.close → new Worker).
+ */
+export function assertMp3RestartGate(input) {
+    const phase = input.phase || 'restart';
+    const base = assertMp3ConcurrencyGate({ ...input, phase });
+    if (!base.ok)
+        return base;
+    return { ok: true, phase };
+}
+/**
+ * Process/cron restart: after `_resetRuntimeForTests` + new `startProcessRuntime`,
+ * flush still emits ``node_process`` with tenant/task samples.
+ */
+export function assertMp3ProcessRestartGate(input) {
+    return assertMp3ConcurrencyGate({
+        ...input,
+        phase: input.phase || 'process_restart',
+        expectedCollector: input.expectedCollector || 'node_process',
+    });
+}
+export function formatMp3GateFailure(result) {
+    if (result.ok)
+        return `MP3 ${result.phase} gate PASS`;
+    return `MP3 ${result.phase} gate FAIL: ${result.reason}`;
+}

package/dist/dogfood/retainDryRunArtifact.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Revision-bound dry-run artifact helpers (N6 evidence prep).
+ * Redacts secrets; does not upload; does not change RunSession flush pipelines.
+ */
+export declare const DRY_RUN_ARTIFACT_SCHEMA = "netgreener_node_dry_run_artifact_v0";
+export type DryRunArtifactV0 = {
+    schema: typeof DRY_RUN_ARTIFACT_SCHEMA;
+    git_sha: string;
+    git_sha_short: string;
+    node_version: string;
+    package_name: string;
+    package_version: string;
+    created_at: string;
+    dry_run: true;
+    upload: 'never';
+    sources: string[];
+    checks: {
+        ok: boolean;
+        has_session_metadata: boolean;
+        has_service_runtime_v0: boolean;
+        collector: string | null;
+    };
+    payload_sha256_prefix: string;
+    payload_redacted: unknown;
+};
+/** Deep-clone JSON-ish values while redacting secret-looking strings/keys. */
+export declare function redactSensitive(value: unknown): unknown;
+export declare function sha256Prefix(value: unknown, chars?: number): string;
+export declare function extractDryRunChecks(payload: unknown): DryRunArtifactV0['checks'];
+export type BuildDryRunArtifactInput = {
+    payload: unknown;
+    gitSha: string;
+    packageName?: string;
+    packageVersion?: string;
+    sources?: string[];
+    createdAt?: string;
+    nodeVersion?: string;
+};
+export declare function buildDryRunArtifact(input: BuildDryRunArtifactInput): DryRunArtifactV0;
+export declare function writeDryRunArtifact(artifactsDir: string, artifact: DryRunArtifactV0): {
+    summaryPath: string;
+    latestPath: string;
+};
+/** Fail closed if redacted text still looks like a live token. */
+export declare function assertArtifactRedacted(artifact: DryRunArtifactV0): void;

package/dist/dogfood/retainDryRunArtifact.js

@@ -0,0 +1,103 @@
+/**
+ * Revision-bound dry-run artifact helpers (N6 evidence prep).
+ * Redacts secrets; does not upload; does not change RunSession flush pipelines.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const DRY_RUN_ARTIFACT_SCHEMA = 'netgreener_node_dry_run_artifact_v0';
+const SECRET_STRING_RE = /\b(?:ngs_[A-Za-z0-9._-]{8,}|Bearer\s+[A-Za-z0-9._~+/=-]{8,}|sk-[A-Za-z0-9]{8,})\b/gi;
+const SECRET_KEY_RE = /^(?:authorization|api[_-]?key|token|access[_-]?token|password|secret|NETGREENER_TOKEN)$/i;
+/** Deep-clone JSON-ish values while redacting secret-looking strings/keys. */
+export function redactSensitive(value) {
+    if (value == null)
+        return value;
+    if (typeof value === 'string') {
+        return value.replace(SECRET_STRING_RE, '[REDACTED]');
+    }
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redactSensitive(v));
+    if (typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (SECRET_KEY_RE.test(k)) {
+                out[k] = '[REDACTED]';
+                continue;
+            }
+            out[k] = redactSensitive(v);
+        }
+        return out;
+    }
+    return String(value);
+}
+export function sha256Prefix(value, chars = 12) {
+    const raw = typeof value === 'string' ? value : JSON.stringify(value);
+    return createHash('sha256').update(raw).digest('hex').slice(0, chars).toUpperCase();
+}
+export function extractDryRunChecks(payload) {
+    const body = payload && typeof payload === 'object' && 'body' in payload
+        ? payload.body
+        : payload;
+    const meta = body && typeof body === 'object' && 'session_metadata' in body
+        ? body.session_metadata
+        : body && typeof body === 'object'
+            ? body
+            : null;
+    const srv = meta && typeof meta === 'object'
+        ? meta.service_runtime_v0
+        : undefined;
+    const collector = srv && typeof srv.collector === 'string' ? String(srv.collector) : null;
+    const hasMeta = Boolean(meta && typeof meta === 'object');
+    const hasSrv = Boolean(srv && typeof srv === 'object');
+    return {
+        ok: hasMeta && hasSrv,
+        has_session_metadata: hasMeta,
+        has_service_runtime_v0: hasSrv,
+        collector,
+    };
+}
+export function buildDryRunArtifact(input) {
+    const redacted = redactSensitive(input.payload);
+    const checks = extractDryRunChecks(input.payload);
+    const sha = String(input.gitSha || 'unknown').trim() || 'unknown';
+    return {
+        schema: DRY_RUN_ARTIFACT_SCHEMA,
+        git_sha: sha,
+        git_sha_short: sha === 'unknown' ? 'unknown' : sha.slice(0, 7),
+        node_version: input.nodeVersion || process.version,
+        package_name: input.packageName || '@netgreener/runtime',
+        package_version: input.packageVersion || '0.0.0',
+        created_at: input.createdAt || new Date().toISOString(),
+        dry_run: true,
+        upload: 'never',
+        sources: input.sources?.length ? [...input.sources] : ['express-dry-run'],
+        checks,
+        payload_sha256_prefix: sha256Prefix(redacted),
+        payload_redacted: redacted,
+    };
+}
+export function writeDryRunArtifact(artifactsDir, artifact) {
+    mkdirSync(artifactsDir, { recursive: true });
+    const stamp = artifact.created_at.replace(/[:.]/g, '-');
+    const summaryPath = join(artifactsDir, `${artifact.git_sha_short}-${stamp}-summary.json`);
+    const latestPath = join(artifactsDir, 'latest-summary.json');
+    const json = `${JSON.stringify(artifact, null, 2)}\n`;
+    writeFileSync(summaryPath, json, 'utf8');
+    writeFileSync(latestPath, json, 'utf8');
+    return { summaryPath, latestPath };
+}
+/** Fail closed if redacted text still looks like a live token. */
+export function assertArtifactRedacted(artifact) {
+    const blob = JSON.stringify(artifact);
+    if (/\bngs_[A-Za-z0-9._-]{8,}\b/.test(blob)) {
+        throw new Error('dry-run artifact still contains an ngs_ token (redaction failed)');
+    }
+    if (/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/i.test(blob)) {
+        throw new Error('dry-run artifact still contains a Bearer token (redaction failed)');
+    }
+    if (artifact.upload !== 'never' || artifact.dry_run !== true) {
+        throw new Error('dry-run artifact must declare dry_run=true and upload=never');
+    }
+}

package/dist/dogfood/tenantDogfoodGates.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Gates for Node tenant dogfood (experimental v0).
+ *
+ * Keeps vendor stubs narrow and live uploads honest:
+ * - Stub decision uses **parsed hostname** boundaries (not path/query substrings).
+ * - Configured NetGreener API destination always takes precedence (never stubbed).
+ * - Failed live uploads must fail the run.
+ */
+/** Registrable / DNS suffixes for vendor hosts dogfood may stub. */
+export declare const VENDOR_FETCH_HOST_SUFFIXES: readonly ["cognitive.microsoft.com", "cognitiveservices.azure.com", "openai.com", "openai.azure.com"];
+/** @deprecated Use VENDOR_FETCH_HOST_SUFFIXES (hostname suffixes, not URL substrings). */
+export declare const VENDOR_FETCH_HOST_MARKERS: readonly ["cognitive.microsoft.com", "cognitiveservices.azure.com", "openai.com", "openai.azure.com"];
+export type DogfoodUploadResult = {
+    ok: true;
+    status: number;
+    body?: unknown;
+    dryRun?: boolean;
+} | {
+    ok: false;
+    status?: number;
+    error: string;
+    body?: unknown;
+    dryRun?: boolean;
+};
+export type VendorStubOptions = {
+    /** Configured NetGreener API base URL — its host is never stubbed. */
+    apiBaseUrl?: string | null;
+};
+export declare function resolveFetchUrl(input: RequestInfo | URL): string;
+/**
+ * Extract hostname from a fetch destination. Returns null when the input is
+ * not an absolute http(s) URL (relative paths are not stubbed).
+ */
+export declare function parseFetchHostname(input: RequestInfo | URL | string): string | null;
+/** True when hostname is exactly a vendor suffix or a subdomain of one. */
+export declare function hostnameMatchesVendor(hostname: string): boolean;
+export declare function parseApiHostname(apiBaseUrl?: string | null): string | null;
+/** Explicit API destination never stubs, even on a lookalike/vendor-named host. */
+export declare function isConfiguredApiDestination(hostname: string, apiBaseUrl?: string | null): boolean;
+/**
+ * True only for explicit vendor hostnames that dogfood may stub.
+ * Path/query substrings and lookalike hosts do not match.
+ * Configured API host always wins (real HTTP).
+ */
+export declare function shouldStubVendorFetch(input: RequestInfo | URL | string, opts?: VendorStubOptions): boolean;
+export declare function stubVendorResponse(input: RequestInfo | URL | string): Response;
+/**
+ * Wrap fetch so only known vendor **hostnames** are stubbed.
+ * The configured API destination always uses real HTTP.
+ */
+export declare function createVendorAwareFetch(realFetch: typeof fetch, opts?: VendorStubOptions): typeof fetch;
+export declare function assertUploadForMode(label: string, result: DogfoodUploadResult | null | undefined, opts: {
+    live: boolean;
+}): {
+    ok: boolean;
+    reason?: string;
+};
+/**
+ * In live mode, never treat a local onFlush payload as proof of persistence.
+ * In dry-run, allow the dry-run body or the captured onFlush payload.
+ */
+export declare function sessionMetadataForDogfood(opts: {
+    live: boolean;
+    flushResult: DogfoodUploadResult | null | undefined;
+    flushPayload?: {
+        session_metadata?: unknown;
+    } | null;
+    label?: string;
+}): {
+    sessionMetadata: Record<string, unknown> | null;
+    uploadGate: {
+        ok: boolean;
+        reason?: string;
+    };
+};
+export declare function extractPersistedRunId(uploadBody: unknown): number | string | null;