@tiangong-lca/cli 0.1.0 → 0.1.2

package/dist/src/lib/dataset-source-upload-attachments.d.ts

@@ -0,0 +1,109 @@
+import type { FetchLike } from './http.js';
+type JsonObject = Record<string, unknown>;
+export type DigitalFileRefKind = 'local' | 'remote' | 'empty';
+export type DigitalFileReference = {
+    source_id: string | null;
+    source_version: string | null;
+    original_uri: string;
+    kind: DigitalFileRefKind;
+    resolved_file: string | null;
+    bucket_key: string | null;
+    rewritten_uri: string | null;
+    status: 'rewritten' | 'left_as_is' | 'unresolved';
+};
+export type AttachmentFileReport = {
+    bucket_key: string;
+    source_path: string;
+    size_bytes: number;
+    content_type: string;
+    referenced_by: string[];
+    status: 'planned' | 'uploaded' | 'verified' | 'failed';
+    error: string | null;
+};
+export type DatasetSourceUploadAttachmentsReport = {
+    schema_version: 1;
+    generated_at_utc: string;
+    status: 'planned_attachment_upload' | 'uploaded_attachments' | 'completed_with_failures' | 'completed_with_unresolved_refs';
+    mode: 'dry-run' | 'commit';
+    bucket: string;
+    external_docs_dir: string;
+    summary: {
+        sources_scanned: number;
+        local_refs: number;
+        remote_refs: number;
+        unresolved_refs: number;
+        files_planned: number;
+        files_uploaded: number;
+        files_failed: number;
+        sources_rewritten: number;
+    };
+    files: AttachmentFileReport[];
+    references: DigitalFileReference[];
+    artifacts: {
+        report: string;
+        rewritten_sources: string;
+    };
+};
+export type RunDatasetSourceUploadAttachmentsOptions = {
+    inputPath: string;
+    externalDocsDir: string;
+    outDir?: string | null;
+    bucket?: string | null;
+    commit?: boolean;
+    verify?: boolean;
+    timeoutMs?: number;
+    env: NodeJS.ProcessEnv;
+    fetchImpl: FetchLike;
+    now?: Date;
+};
+declare function trimToken(value: unknown): string | null;
+declare function caughtErrorMessage(error: unknown): string;
+declare function normalizeTimeoutMs(value: number | undefined): number;
+export declare function classifyDigitalFileUri(uri: unknown): DigitalFileRefKind;
+export declare function digitalFileBasename(uri: string): string;
+export declare function mimeTypeForFile(fileName: string): string;
+declare function buildExternalDocsIndex(externalDocsDir: string): Map<string, string>;
+declare function digitalFileNode(row: JsonObject): JsonObject | null;
+declare function sourceIdentity(row: JsonObject): {
+    id: string | null;
+    version: string | null;
+};
+declare function entryUri(entry: unknown): string;
+declare function withRewrittenUri(entry: unknown, rewrittenUri: string): unknown;
+export type ResolvedReference = {
+    reference: DigitalFileReference;
+    entryIndex: number;
+};
+declare function resolveReferences(identity: {
+    id: string | null;
+    version: string | null;
+}, entries: unknown[], fileIndex: Map<string, string>, bucket: string): ResolvedReference[];
+export declare function digitalFileEntries(value: unknown): unknown[];
+declare function rewriteDigitalFileValue(value: unknown, resolved: ResolvedReference[]): unknown;
+declare function loadSourceRows(inputPath: string): {
+    path: string;
+    row: JsonObject;
+}[];
+declare function parseJson(text: string, file: string): unknown;
+declare function parseRowObject(text: string, file: string): JsonObject;
+export declare function runDatasetSourceUploadAttachments(options: RunDatasetSourceUploadAttachmentsOptions): Promise<DatasetSourceUploadAttachmentsReport>;
+export declare const __testInternals: {
+    buildExternalDocsIndex: typeof buildExternalDocsIndex;
+    caughtErrorMessage: typeof caughtErrorMessage;
+    classifyDigitalFileUri: typeof classifyDigitalFileUri;
+    digitalFileBasename: typeof digitalFileBasename;
+    digitalFileEntries: typeof digitalFileEntries;
+    digitalFileNode: typeof digitalFileNode;
+    entryUri: typeof entryUri;
+    loadSourceRows: typeof loadSourceRows;
+    mimeTypeForFile: typeof mimeTypeForFile;
+    normalizeTimeoutMs: typeof normalizeTimeoutMs;
+    parseJson: typeof parseJson;
+    parseRowObject: typeof parseRowObject;
+    resolveReferences: typeof resolveReferences;
+    rewriteDigitalFileValue: typeof rewriteDigitalFileValue;
+    sourceIdentity: typeof sourceIdentity;
+    trimToken: typeof trimToken;
+    withRewrittenUri: typeof withRewrittenUri;
+};
+export {};

package/dist/src/lib/dataset-validate.d.ts

@@ -0,0 +1,62 @@
+import { type DatasetKind, type DatasetRowInput } from './dataset-local.js';
+import { type SafeParseSchema, type SdkValidationFactory } from './tidas-sdk-validation.js';
+type DatasetValidateType = 'auto' | DatasetKind;
+export type DatasetValidateIssue = {
+    path: string;
+    message: string;
+    code: string;
+};
+export type DatasetValidateRowReport = {
+    index: number;
+    id: string | null;
+    version: string | null;
+    type: DatasetKind | null;
+    status: 'valid' | 'invalid';
+    validator: string | null;
+    issue_count: number;
+    issues: DatasetValidateIssue[];
+};
+export type DatasetValidateReport = {
+    generated_at_utc: string;
+    input_path: string;
+    requested_type: DatasetValidateType;
+    status: 'completed' | 'completed_with_failures';
+    counts: {
+        total: number;
+        valid: number;
+        invalid: number;
+        by_type: Record<DatasetKind, number>;
+    };
+    files: {
+        report: string | null;
+        valid_rows: string | null;
+        invalid_rows: string | null;
+    };
+    rows: DatasetValidateRowReport[];
+};
+export type RunDatasetValidateOptions = {
+    inputPath: string;
+    type?: string | null;
+    outDir?: string | null;
+    rawInput?: unknown;
+    now?: Date;
+    schemas?: Partial<Record<DatasetKind, SafeParseSchema>>;
+};
+export declare function collectImportContentIssues(payload: unknown): DatasetValidateIssue[];
+declare function normalizeType(value: string | null | undefined): DatasetValidateType;
+declare function schemaForKind(kind: DatasetKind, schemas: Partial<Record<DatasetKind, SafeParseSchema>> | undefined): {
+    validator: string;
+    schema: SafeParseSchema;
+    createEntity: SdkValidationFactory | null;
+};
+declare function validateRow(row: DatasetRowInput, requestedType: DatasetValidateType, schemas: Partial<Record<DatasetKind, SafeParseSchema>> | undefined): DatasetValidateRowReport;
+export declare function runDatasetValidate(options: RunDatasetValidateOptions): Promise<DatasetValidateReport>;
+export declare const __testInternals: {
+    ENTITY_FACTORY_EXPORTS: Record<DatasetKind, "CAS_NUMBER_CHECKSUM_ERROR_CODE" | "CAS_NUMBER_PATTERN" | "CHINESE_CHARACTER_RE" | "ContactCategorySchema" | "ContactSchema" | "DEFAULT_VALIDATION_CONFIG" | "DEFAULT_XML_PARSE_OPTIONS" | "DEFAULT_XML_UNPARSE_OPTIONS" | "ErrorSeverity" | "FlowElementaryCategorySchema" | "FlowProductCategorySchema" | "FlowPropertyCategorySchema" | "FlowPropertySchema" | "FlowSchema" | "LCIAMethodCategorySchema" | "LCIAMethodSchema" | "LifeCycleModelSchema" | "LocationCategorySchema" | "ProcessCategorySchema" | "ProcessSchema" | "SUPPORTED_CATEGORIES" | "SourceCategorySchema" | "SourceSchema" | "TIDAS_LANGUAGE_CODES" | "TIDAS_LANGUAGE_CODE_SET" | "TidasContact" | "TidasEntity" | "TidasFlow" | "TidasFlowProperty" | "TidasLCIAMethod" | "TidasLifeCycleModel" | "TidasProcess" | "TidasSource" | "TidasUnitGroup" | "UnitGroupCategorySchema" | "UnitGroupSchema" | "ValidationUtils" | "batchSuggest" | "buildCategoryReport" | "buildPackageReport" | "categoryValidate" | "collectClassificationIssues" | "collectFlowSchemaGapIssues" | "collectLocalizedTextIssues" | "compareMethodologyWithSchema" | "convertDirectory" | "convertFormat" | "copyEilcdAssets" | "copyRuntimeAssetDir" | "copyTidasAssets" | "createContact" | "createContactFromJSON" | "createContactsBatch" | "createFlow" | "createFlowFromJSON" | "createFlowPropertiesBatch" | "createFlowProperty" | "createFlowPropertyFromJSON" | "createFlowsBatch" | "createLCIAMethod" | "createLCIAMethodFromJSON" | "createLCIAMethodsBatch" | "createLifeCycleModel" | "createLifeCycleModelFromJSON" | "createLifeCycleModelsBatch" | "createProcess" | "createProcessFromJSON" | "createProcessesBatch" | "createSource" | "createSourceFromJSON" | "createSourcesBatch" | "createStaticValidationMethod" | "createTidasEntity" | "createUnitGroup" | "createUnitGroupFromJSON" | "createUnitGroupsBatch" | "createValidationMethod" | "datasetFromXml" | "datasetToXml" | "deepClone" | "default" | "extractMethodologyPaths" | "extractSchemaPaths" | "get" | "getAvailableDataTypes" | "getAvailableTidasContractKinds" | "getGlobalValidationConfig" | "getGlobalValidationMode" | "getTidasContractPack" | "getTidasMethodologyData" | "getTidasMethodologyText" | "getTidasRuntimeRuleset" | "getTidasSchemaData" | "getTidasSchemaText" | "globalConfig" | "isValidCASNumber" | "loadConfigFromEnvironment" | "merge" | "normalizeMethodologyPath" | "normalizeTidasContractKind" | "parseWithZod" | "parseXml" | "resetGlobalConfig" | "resolveRuntimeAssetDir" | "resolveRuntimeAssetsDir" | "set" | "setGlobalValidationConfig" | "setGlobalValidationMode" | "suggestData" | "suggestRawData" | "summarizeIssues" | "unparseXml" | "updatePath" | "validateBatch" | "validateBundledMethodologies" | "validateElementaryFlowsClassificationHierarchy" | "validateLocalizedTextLanguageConstraints" | "validateMethodologySchemaParity" | "validatePackageDir" | "validateProcessesClassificationHierarchy" | "validateProductFlowsClassificationHierarchy" | "validateSourcesClassificationHierarchy" | "validateSuggestionApiKey" | "validateWithZod">;
+    SCHEMA_EXPORTS: Record<DatasetKind, "CAS_NUMBER_CHECKSUM_ERROR_CODE" | "CAS_NUMBER_PATTERN" | "CHINESE_CHARACTER_RE" | "ContactCategorySchema" | "ContactSchema" | "DEFAULT_VALIDATION_CONFIG" | "DEFAULT_XML_PARSE_OPTIONS" | "DEFAULT_XML_UNPARSE_OPTIONS" | "ErrorSeverity" | "FlowElementaryCategorySchema" | "FlowProductCategorySchema" | "FlowPropertyCategorySchema" | "FlowPropertySchema" | "FlowSchema" | "LCIAMethodCategorySchema" | "LCIAMethodSchema" | "LifeCycleModelSchema" | "LocationCategorySchema" | "ProcessCategorySchema" | "ProcessSchema" | "SUPPORTED_CATEGORIES" | "SourceCategorySchema" | "SourceSchema" | "TIDAS_LANGUAGE_CODES" | "TIDAS_LANGUAGE_CODE_SET" | "TidasContact" | "TidasEntity" | "TidasFlow" | "TidasFlowProperty" | "TidasLCIAMethod" | "TidasLifeCycleModel" | "TidasProcess" | "TidasSource" | "TidasUnitGroup" | "UnitGroupCategorySchema" | "UnitGroupSchema" | "ValidationUtils" | "batchSuggest" | "buildCategoryReport" | "buildPackageReport" | "categoryValidate" | "collectClassificationIssues" | "collectFlowSchemaGapIssues" | "collectLocalizedTextIssues" | "compareMethodologyWithSchema" | "convertDirectory" | "convertFormat" | "copyEilcdAssets" | "copyRuntimeAssetDir" | "copyTidasAssets" | "createContact" | "createContactFromJSON" | "createContactsBatch" | "createFlow" | "createFlowFromJSON" | "createFlowPropertiesBatch" | "createFlowProperty" | "createFlowPropertyFromJSON" | "createFlowsBatch" | "createLCIAMethod" | "createLCIAMethodFromJSON" | "createLCIAMethodsBatch" | "createLifeCycleModel" | "createLifeCycleModelFromJSON" | "createLifeCycleModelsBatch" | "createProcess" | "createProcessFromJSON" | "createProcessesBatch" | "createSource" | "createSourceFromJSON" | "createSourcesBatch" | "createStaticValidationMethod" | "createTidasEntity" | "createUnitGroup" | "createUnitGroupFromJSON" | "createUnitGroupsBatch" | "createValidationMethod" | "datasetFromXml" | "datasetToXml" | "deepClone" | "default" | "extractMethodologyPaths" | "extractSchemaPaths" | "get" | "getAvailableDataTypes" | "getAvailableTidasContractKinds" | "getGlobalValidationConfig" | "getGlobalValidationMode" | "getTidasContractPack" | "getTidasMethodologyData" | "getTidasMethodologyText" | "getTidasRuntimeRuleset" | "getTidasSchemaData" | "getTidasSchemaText" | "globalConfig" | "isValidCASNumber" | "loadConfigFromEnvironment" | "merge" | "normalizeMethodologyPath" | "normalizeTidasContractKind" | "parseWithZod" | "parseXml" | "resetGlobalConfig" | "resolveRuntimeAssetDir" | "resolveRuntimeAssetsDir" | "set" | "setGlobalValidationConfig" | "setGlobalValidationMode" | "suggestData" | "suggestRawData" | "summarizeIssues" | "unparseXml" | "updatePath" | "validateBatch" | "validateBundledMethodologies" | "validateElementaryFlowsClassificationHierarchy" | "validateLocalizedTextLanguageConstraints" | "validateMethodologySchemaParity" | "validatePackageDir" | "validateProcessesClassificationHierarchy" | "validateProductFlowsClassificationHierarchy" | "validateSourcesClassificationHierarchy" | "validateSuggestionApiKey" | "validateWithZod">;
+    collectImportContentIssues: typeof collectImportContentIssues;
+    normalizeType: typeof normalizeType;
+    schemaForKind: typeof schemaForKind;
+    validateRow: typeof validateRow;
+};
+export {};

package/dist/src/lib/dotenv.d.ts

@@ -0,0 +1,6 @@
+export type DotEnvLoadResult = {
+    loaded: boolean;
+    path: string;
+    count: number;
+};
+export declare function loadDotEnv(cwd: string, env: NodeJS.ProcessEnv): DotEnvLoadResult;

package/dist/src/lib/env.d.ts

@@ -0,0 +1,59 @@
+export type EnvSpec = {
+    key: string;
+    required: boolean;
+    description: string;
+    defaultValue?: string;
+};
+export type ResolvedEnv = {
+    key: string;
+    source: 'env' | 'default' | 'missing';
+    value: string | null;
+    present: boolean;
+};
+export declare const ENV_KEYS: {
+    readonly apiBaseUrl: 'TIANGONG_LCA_API_BASE_URL';
+    readonly apiKey: 'TIANGONG_LCA_API_KEY';
+    readonly region: 'TIANGONG_LCA_REGION';
+    readonly supabasePublishableKey: 'TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY';
+    readonly sessionFile: 'TIANGONG_LCA_SESSION_FILE';
+    readonly disableSessionCache: 'TIANGONG_LCA_DISABLE_SESSION_CACHE';
+    readonly forceReauth: 'TIANGONG_LCA_FORCE_REAUTH';
+};
+export declare const ENV_SPECS: EnvSpec[];
+export type DoctorCheck = {
+    key: string;
+    description: string;
+    required: boolean;
+    source: ResolvedEnv['source'];
+    present: boolean;
+    valuePreview: string | null;
+};
+export type DoctorReport = {
+    ok: boolean;
+    loadedDotEnv: boolean;
+    dotEnvPath: string;
+    dotEnvKeysLoaded: number;
+    checks: DoctorCheck[];
+};
+export type RuntimeEnv = {
+    apiBaseUrl: string | null;
+    apiKey: string | null;
+    region: string;
+    supabasePublishableKey: string | null;
+    sessionFile: string | null;
+    disableSessionCache: boolean;
+    forceReauth: boolean;
+};
+declare function parseBooleanEnv(value: string | null): boolean;
+export declare function resolveEnv(spec: EnvSpec, env: NodeJS.ProcessEnv): ResolvedEnv;
+export declare function readRuntimeEnv(env: NodeJS.ProcessEnv): RuntimeEnv;
+export declare function maskSecret(value: string | null): string | null;
+export declare function buildDoctorReport(env: NodeJS.ProcessEnv, dotEnvStatus: {
+    loaded: boolean;
+    path: string;
+    count: number;
+}): DoctorReport;
+export declare const __testInternals: {
+    parseBooleanEnv: typeof parseBooleanEnv;
+};
+export {};

package/dist/src/lib/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly details?: unknown;
+    constructor(message: string, options?: {
+        code?: string;
+        exitCode?: number;
+        details?: unknown;
+    });
+}
+export type ErrorPayload = {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+};
+export declare function toErrorPayload(error: unknown): ErrorPayload;

package/dist/src/lib/flow-build-alias-map.d.ts

@@ -0,0 +1,80 @@
+import { type FlowRecord, type JsonRecord } from './flow-governance.js';
+type FlowIndex = {
+    records: FlowRecord[];
+    byUuid: Record<string, FlowRecord[]>;
+    byUuidVersion: Record<string, FlowRecord>;
+    byName: Record<string, FlowRecord[]>;
+};
+export type FlowBuildAliasMapFiles = {
+    out_dir: string;
+    alias_plan: string;
+    alias_plan_jsonl: string;
+    flow_alias_map: string;
+    manual_review_queue: string;
+    summary: string;
+};
+export type FlowBuildAliasMapSummary = {
+    old_flow_count: number;
+    new_flow_count: number;
+    alias_entries_versioned: number;
+    alias_entries_uuid_only: number;
+    manual_review_count: number;
+    decision_counts: Record<string, number>;
+};
+export type FlowAliasPlanAction = {
+    old_flow_id: string;
+    old_flow_version: string;
+    old_flow_name: string;
+    old_flow_type: string;
+    decision: 'no_alias_needed' | 'alias_map_entry' | 'manual_review';
+    reason: string;
+    target_flow_id?: string;
+    target_flow_version?: string;
+    target_flow_name?: string;
+    target_flow_type?: string;
+    candidate_refs?: Array<Record<string, string>>;
+};
+export type FlowBuildAliasMapReport = {
+    schema_version: 1;
+    generated_at_utc: string;
+    status: 'completed_local_flow_build_alias_map';
+    old_flow_files: string[];
+    new_flow_files: string[];
+    seed_alias_map_file: string | null;
+    out_dir: string;
+    summary: FlowBuildAliasMapSummary;
+    files: FlowBuildAliasMapFiles;
+};
+export type RunFlowBuildAliasMapOptions = {
+    oldFlowFiles: string[];
+    newFlowFiles: string[];
+    seedAliasMapFile?: string | null;
+    outDir: string;
+};
+type FlowBuildAliasMapDeps = {
+    now?: () => Date;
+};
+declare function assertInputFile(inputFile: string, requiredCode: string, missingCode: string): string;
+declare function assertInputFiles(inputFiles: string[], requiredCode: string, missingCode: string): string[];
+declare function assertOutDir(outDir: string): string;
+declare function readJsonObjectFile(filePath: string, requiredCode: string, missingCode: string, invalidCode: string): JsonRecord;
+declare function buildFlowIndex(rows: JsonRecord[]): FlowIndex;
+declare function aliasLookup(aliasMap: JsonRecord, flowUuid: string, flowVersion: string | null): JsonRecord | null;
+declare function candidateRef(record: FlowRecord, includeType?: boolean): Record<string, string>;
+declare function planAlias(oldRecord: FlowRecord, newIndex: FlowIndex, seedAliasMap: JsonRecord): FlowAliasPlanAction;
+declare function buildDecisionCounts(actions: FlowAliasPlanAction[]): Record<string, number>;
+declare function buildOutputFiles(outDir: string): FlowBuildAliasMapFiles;
+export declare function runFlowBuildAliasMap(options: RunFlowBuildAliasMapOptions, deps?: FlowBuildAliasMapDeps): Promise<FlowBuildAliasMapReport>;
+export declare const __testInternals: {
+    assertInputFile: typeof assertInputFile;
+    assertInputFiles: typeof assertInputFiles;
+    assertOutDir: typeof assertOutDir;
+    readJsonObjectFile: typeof readJsonObjectFile;
+    buildFlowIndex: typeof buildFlowIndex;
+    aliasLookup: typeof aliasLookup;
+    candidateRef: typeof candidateRef;
+    planAlias: typeof planAlias;
+    buildDecisionCounts: typeof buildDecisionCounts;
+    buildOutputFiles: typeof buildOutputFiles;
+};
+export {};

package/dist/src/lib/flow-fetch-rows.d.ts

@@ -0,0 +1,70 @@
+import { type JsonRecord } from './flow-governance.js';
+import type { FetchLike } from './http.js';
+import { type SupabaseFlowLookup } from './flow-read.js';
+type FlowFetchRef = {
+    id: string;
+    version: string | null;
+    userId: string | null;
+    stateCode: number | null;
+    clusterId: string | null;
+    source: string | null;
+};
+type FlowFetchMaterializationContext = {
+    input_index: number;
+    requested_ref: {
+        id: string;
+        version: string | null;
+        user_id: string | null;
+        state_code: number | null;
+        cluster_id: string | null;
+        source: string | null;
+    };
+    resolution: SupabaseFlowLookup['resolution'];
+    source_url: string;
+    resolved_flow_id: string;
+    resolved_version: string;
+};
+type FlowFetchSummaryStatus = 'completed_flow_row_materialization' | 'completed_flow_row_materialization_with_gaps';
+export type RunFlowFetchRowsOptions = {
+    refsFile: string;
+    outDir: string;
+    allowLatestFallback?: boolean;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+    now?: Date;
+};
+export type FlowFetchRowsReport = {
+    schema_version: 1;
+    generated_at_utc: string;
+    status: FlowFetchSummaryStatus;
+    refs_file: string;
+    out_dir: string;
+    allow_latest_fallback: boolean;
+    requested_ref_count: number;
+    resolved_ref_count: number;
+    qa_input_row_count: number;
+    duplicate_qa_input_rows_collapsed: number;
+    missing_ref_count: number;
+    ambiguous_ref_count: number;
+    resolution_counts: Record<SupabaseFlowLookup['resolution'], number>;
+    files: {
+        resolved_flow_rows: string;
+        qa_input_rows: string;
+        fetch_summary: string;
+        missing_flow_refs: string;
+        ambiguous_flow_refs: string;
+    };
+};
+declare function normalizeToken(value: unknown): string | null;
+declare function normalizeOptionalNonNegativeInteger(value: unknown, label: string, code: string): number | null;
+declare function normalizeFlowFetchRef(row: JsonRecord, index: number): FlowFetchRef;
+declare function toRequestedRefSummary(ref: FlowFetchRef): FlowFetchMaterializationContext['requested_ref'];
+export declare function runFlowFetchRows(options: RunFlowFetchRowsOptions): Promise<FlowFetchRowsReport>;
+export declare const __testInternals: {
+    normalizeFlowFetchRef: typeof normalizeFlowFetchRef;
+    normalizeOptionalNonNegativeInteger: typeof normalizeOptionalNonNegativeInteger;
+    normalizeToken: typeof normalizeToken;
+    toRequestedRefSummary: typeof toRequestedRefSummary;
+};
+export {};

package/dist/src/lib/flow-get.d.ts

@@ -0,0 +1,35 @@
+import type { FetchLike } from './http.js';
+import { type SupabaseFlowLookup } from './flow-read.js';
+type JsonObject = Record<string, unknown>;
+export type RunFlowGetOptions = {
+    flowId: string;
+    version?: string | null;
+    userId?: string | null;
+    stateCode?: number | null;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+    now?: Date;
+};
+export type FlowGetReport = {
+    schema_version: 1;
+    generated_at_utc: string;
+    status: 'resolved_remote_flow';
+    flow_id: string;
+    requested_version: string | null;
+    requested_user_id: string | null;
+    requested_state_code: number | null;
+    resolved_version: string;
+    resolution: SupabaseFlowLookup['resolution'];
+    source_url: string;
+    modified_at: string | null;
+    user_id: string | null;
+    state_code: number | null;
+    flow: JsonObject;
+};
+declare function normalizeToken(value: string | null | undefined): string | null;
+export declare function runFlowGet(options: RunFlowGetOptions): Promise<FlowGetReport>;
+export declare const __testInternals: {
+    normalizeToken: typeof normalizeToken;
+};
+export {};

package/dist/src/lib/flow-governance.d.ts

@@ -0,0 +1,22 @@
+export type JsonRecord = Record<string, unknown>;
+export declare function isRecord(value: unknown): value is JsonRecord;
+export type FlowRecord = {
+    id: string;
+    version: string;
+    name: string;
+    flowType: string;
+    shortDescription: JsonRecord | null;
+    row: JsonRecord;
+};
+export declare function listify<T>(value: T | T[] | null | undefined): T[];
+export declare function deepGet(value: unknown, pathParts: string[], defaultValue?: unknown): unknown;
+export declare function coerceText(value: unknown): string;
+export declare function firstLangEntry(value: unknown, fallback?: string): JsonRecord | null;
+export declare function normalizeText(value: string): string;
+export declare function datasetPayloadFromRow(row: JsonRecord): JsonRecord;
+export declare function flowDatasetFromRow(row: JsonRecord): JsonRecord;
+export declare function extractFlowRecord(row: JsonRecord): FlowRecord;
+export declare function loadRowsFromFile(filePath: string): JsonRecord[];
+export declare const __testInternals: {
+    isRecord: typeof isRecord;
+};

package/dist/src/lib/flow-list.d.ts

@@ -0,0 +1,57 @@
+import type { FetchLike } from './http.js';
+type JsonObject = Record<string, unknown>;
+export type RunFlowListOptions = {
+    ids?: string[];
+    version?: string | null;
+    userId?: string | null;
+    stateCodes?: number[];
+    typeOfDataset?: string[];
+    limit?: number | null;
+    offset?: number | null;
+    all?: boolean;
+    pageSize?: number | null;
+    order?: string | null;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+    now?: Date;
+};
+export type FlowListReport = {
+    schema_version: 1;
+    generated_at_utc: string;
+    status: 'listed_remote_flows';
+    filters: {
+        ids: string[];
+        requested_version: string | null;
+        requested_user_id: string | null;
+        requested_state_codes: number[];
+        requested_type_of_dataset: string[];
+        order: string;
+        all: boolean;
+        limit: number | null;
+        offset: number;
+        page_size: number | null;
+    };
+    count: number;
+    source_urls: string[];
+    rows: Array<{
+        id: string;
+        version: string;
+        user_id: string | null;
+        state_code: number | null;
+        modified_at: string | null;
+        flow: JsonObject;
+    }>;
+};
+declare function normalizeToken(value: string | null | undefined): string | null;
+declare function nowIso(now?: Date): string;
+declare function toPositiveInteger(value: number | null | undefined, label: string, code: string): number;
+declare function toNonNegativeInteger(value: number | null | undefined, label: string, code: string): number;
+export declare function runFlowList(options: RunFlowListOptions): Promise<FlowListReport>;
+export declare const __testInternals: {
+    normalizeToken: typeof normalizeToken;
+    nowIso: typeof nowIso;
+    toPositiveInteger: typeof toPositiveInteger;
+    toNonNegativeInteger: typeof toNonNegativeInteger;
+};
+export {};

package/dist/src/lib/flow-materialize-decisions.d.ts

@@ -0,0 +1,67 @@
+import { type FlowRecord, type JsonRecord } from './flow-governance.js';
+type FlowRef = {
+    id: string;
+    version: string;
+};
+type SupportedDecision = 'merge_keep_one' | 'keep_distinct' | 'blocked_missing_db_flow';
+type NormalizedDecision = {
+    clusterId: string;
+    decision: SupportedDecision;
+    reason: string | null;
+    canonicalRef: FlowRef | null;
+    memberRefs: FlowRef[];
+};
+type IndexedFlowRow = {
+    key: string;
+    row: JsonRecord;
+    record: FlowRecord;
+};
+type FlowMaterializeDecisionsFiles = {
+    canonical_map: string;
+    rewrite_plan: string;
+    semantic_merge_seed: string;
+    summary: string;
+    blocked_clusters: string;
+};
+type FlowMaterializeDecisionCounts = {
+    input_decisions: number;
+    materialized_clusters: number;
+    blocked_clusters: number;
+    canonical_map_entries: number;
+    rewrite_actions: number;
+    seed_alias_entries: number;
+    decision_counts: Record<SupportedDecision, number>;
+    blocked_reason_counts: Record<string, number>;
+};
+export type FlowMaterializeDecisionsReport = {
+    schema_version: 1;
+    generated_at_utc: string;
+    status: 'completed_local_flow_decision_materialization' | 'completed_local_flow_decision_materialization_with_blocked_clusters';
+    decision_file: string;
+    flow_rows_file: string;
+    out_dir: string;
+    counts: FlowMaterializeDecisionCounts;
+    files: FlowMaterializeDecisionsFiles;
+};
+export type RunFlowMaterializeDecisionsOptions = {
+    decisionFile: string;
+    flowRowsFile: string;
+    outDir: string;
+    now?: Date;
+};
+declare function parseFlowRefString(value: string, code: string): FlowRef;
+declare function parseFlowRefLike(value: unknown, code: string): FlowRef | null;
+declare function uniqueFlowRefs(refs: FlowRef[]): FlowRef[];
+declare function parseDecisionRow(row: JsonRecord, index: number): NormalizedDecision;
+declare function buildFlowIndex(rows: JsonRecord[]): Map<string, IndexedFlowRow>;
+declare function buildOutputFiles(outDir: string): FlowMaterializeDecisionsFiles;
+export declare function runFlowMaterializeDecisions(options: RunFlowMaterializeDecisionsOptions): Promise<FlowMaterializeDecisionsReport>;
+export declare const __testInternals: {
+    parseDecisionRow: typeof parseDecisionRow;
+    parseFlowRefLike: typeof parseFlowRefLike;
+    parseFlowRefString: typeof parseFlowRefString;
+    uniqueFlowRefs: typeof uniqueFlowRefs;
+    buildFlowIndex: typeof buildFlowIndex;
+    buildOutputFiles: typeof buildOutputFiles;
+};
+export {};

package/dist/src/lib/flow-payload-validation.d.ts

@@ -0,0 +1,32 @@
+import { type SafeParseSchema, type SdkValidationFactory } from './tidas-sdk-validation.js';
+type JsonObject = Record<string, unknown>;
+export declare const FLOW_SCHEMA_VALIDATOR = "@tiangong-lca/tidas-sdk/FlowSchema";
+export type FlowPayloadValidationIssue = {
+    path: string;
+    message: string;
+    code: string;
+};
+export type FlowPayloadValidationResult = {
+    ok: true;
+    validator: string;
+    issue_count: 0;
+    issues: [];
+} | {
+    ok: false;
+    validator: string;
+    issue_count: number;
+    issues: FlowPayloadValidationIssue[];
+};
+declare function getFlowSchema(sdk?: {
+    FlowSchema?: SafeParseSchema;
+}): SafeParseSchema;
+declare function getFlowFactory(sdk?: {
+    createFlow?: unknown;
+}): SdkValidationFactory | null;
+export declare function summarizeFlowPayloadValidation(result: FlowPayloadValidationResult): string;
+export declare function validateFlowPayload(payload: JsonObject, schema?: SafeParseSchema, createEntity?: SdkValidationFactory | null): FlowPayloadValidationResult;
+export declare const __testInternals: {
+    getFlowSchema: typeof getFlowSchema;
+    getFlowFactory: typeof getFlowFactory;
+};
+export {};