@ingestron/core 0.12.0

package/dist/core/workflows.js

@@ -0,0 +1,438 @@
+import { packageReferenceSchema } from "./schema.js";
+import { connectorPackageSchema } from "./connector-package.js";
+/** User workflows shared by CLI and MCP. These compose the existing offline
+ * compiler and isolated plugin APIs. Execution adapters must be separate from
+ * this module: importing metadata never grants permission to run SQL or scripts.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve, relative, dirname } from "node:path";
+import { parseDocument, stringify } from "yaml";
+import { z } from "zod";
+import { Configuration } from "./config.js";
+import { check, digest, canonical } from "./errors.js";
+import { preview, addFlow } from "./authoring.js";
+import { contractDraft } from "./development.js";
+import { validateContract, contractColumns } from "./contracts.js";
+import { providerAuthor, providerReference } from "../plugins/authoring.js";
+import { runProviderCommand } from "./provider-commands.js";
+import { fence, resolvePackage, packageYaml, canonicalPackageReference, } from "./packages.js";
+import { friendlyReference } from "./package-references.js";
+export const identifier = z.string().regex(/^[A-Za-z_][A-Za-z0-9_-]*$/);
+const connection = z
+    .object({
+    binding: identifier.optional(),
+    provider: identifier.optional(),
+    execution: z.enum(["manual", "local"]).optional(),
+    resultPath: z.string().max(1024).optional(),
+})
+    .strict();
+export const sourceSchema = z
+    .object({
+    apiVersion: z.literal("ingestron.source/v1"),
+    id: identifier,
+    type: identifier,
+    format: identifier.optional(),
+    provider: identifier.optional(),
+    execution: z.enum(["manual", "local"]).default("manual"),
+    binding: identifier.optional(),
+    environments: z.record(identifier, connection).default({}),
+})
+    .strict();
+export function sourcePath(id) {
+    return `sources/${identifier.parse(id)}.yaml`;
+}
+export const metadataPath = (id, environment) => `discovery/${identifier.parse(id)}/${identifier.parse(environment)}/metadata.json`;
+export function sourceShow(root, id, environment) {
+    const source = sourceSchema.parse(new Configuration(root).load(sourcePath(id)));
+    check(source.id === id, "SOURCE", "Source filename and identifier differ");
+    const reader = new Configuration(root);
+    check(reader.load().environments[environment], "ENVIRONMENT", `Unknown environment ${environment}`);
+    const path = metadataPath(id, environment);
+    const snapshot = existsSync(fence(root, path))
+        ? reader.load(path)
+        : undefined;
+    const discovery = snapshot
+        ? {
+            path,
+            inputDigest: snapshot.inputDigest,
+            stale: snapshot.sourceDigest !== digest(reader.text(sourcePath(id))),
+            entities: snapshot.contracts?.map((c) => ({
+                id: c.id,
+                physicalNames: c.schema?.map((s) => s.physicalName ?? s.name),
+            })),
+        }
+        : { path, imported: false };
+    return {
+        ...source,
+        discovery,
+        selected: { environment, ...source, ...source.environments[environment] },
+    };
+}
+export function sourceList(root, environment) {
+    const directory = fence(root, "sources");
+    return existsSync(directory)
+        ? readdirSync(directory)
+            .filter((n) => n.endsWith(".yaml"))
+            .sort()
+            .map((n) => {
+            const source = sourceShow(root, n.slice(0, -5), environment);
+            return {
+                id: source.id,
+                type: source.type,
+                format: source.format,
+                execution: source.selected.execution,
+                provider: source.selected.provider,
+            };
+        })
+        : [];
+}
+export function sourceAdd(root, args) {
+    const { id, type, format, provider, execution, binding } = args;
+    const path = sourcePath(id);
+    check(!existsSync(fence(root, path)), "OWNER", `Source ${id} already exists`);
+    const source = sourceSchema.parse({
+        apiVersion: "ingestron.source/v1",
+        id,
+        type,
+        format,
+        provider,
+        execution,
+        binding,
+    });
+    return preview(root, { [path]: stringify(source) });
+}
+export function sourceConfigure(root, args) {
+    const path = sourcePath(args.id), reader = new Configuration(root);
+    const original = sourceSchema.parse(reader.load(path));
+    check(!("id" in args.patch) && !("apiVersion" in args.patch), "SOURCE", "Source identity cannot be changed by a patch");
+    const next = sourceSchema.parse({ ...original, ...args.patch });
+    return preview(root, { [path]: stringify(next) });
+}
+function providerConfiguration(root, selected) {
+    const project = new Configuration(root).load();
+    const configurations = project.providers.configurations;
+    if (!selected)
+        selected = project.defaults?.provider;
+    if (selected && configurations[selected])
+        return selected;
+    const matches = Object.entries(configurations).filter(([, value]) => value.package === selected);
+    check(matches.length === 1, "PROVIDER", "Select an installed provider configuration by name");
+    return matches[0][0];
+}
+/** Register installed provider authoring defaults without overwriting another
+ * provider's bindings or values. Cache installation and registration are distinct
+ * shared operations; a registration conflict leaves the immutable cache usable. */
+function packageEditor(root) {
+    const reader = new Configuration(root);
+    const project = parseDocument(reader.text("project.yaml"));
+    const reference = project.toJS().providers?.$resolve;
+    let providerFile;
+    let providerDoc;
+    if (reference) {
+        check(typeof reference === "string" && !reference.includes("#"), "REFERENCE", "Plugin registration requires a whole providers file, not a fragment");
+        providerFile = relative(root, reader.path(reference));
+        providerDoc = parseDocument(reader.text(providerFile));
+        check(!providerDoc.toJS().packages?.$resolve &&
+            !providerDoc.toJS().configurations?.$resolve, "REFERENCE", "Keep packages and configurations in the providers file for automatic registration");
+        project.set("providers", providerDoc.contents?.clone());
+    }
+    const finish = (files) => {
+        if (providerFile && providerDoc && files["project.yaml"]) {
+            const edited = parseDocument(files["project.yaml"]);
+            providerDoc.contents = edited.get("providers", true);
+            files[providerFile] = providerDoc.toString();
+            edited.set("providers", { $resolve: reference });
+            files["project.yaml"] = edited.toString();
+        }
+        return preview(root, files);
+    };
+    return { reader, project, finish };
+}
+export function pluginConfigure(root, args) {
+    const reference = canonicalPackageReference(args.reference);
+    const sourceManifest = packageYaml(resolvePackage(root, reference).file);
+    if (sourceManifest.apiVersion === "ingestron.connector/v1") {
+        const connector = connectorPackageSchema.parse(sourceManifest);
+        const { project, finish } = packageEditor(root);
+        const name = identifier.parse(args.name ?? connector.id);
+        const at = reference.lastIndexOf("@");
+        const friendly = friendlyReference(reference);
+        const value = {
+            source: friendly.slice(0, friendly.lastIndexOf("@")),
+            version: reference.slice(at + 1),
+        };
+        const previous = project.getIn(["providers", "packages", name]);
+        if (previous) {
+            const old = packageReferenceSchema.parse(project.toJS().providers.packages[name]);
+            check(canonical(old) === canonical(value) ||
+                (args.update && old.source === value.source), "CONFLICT", "Connector package key already exists; choose a different name");
+        }
+        project.setIn(["providers", "packages", name], `${value.source}@${value.version}`);
+        return finish({ "project.yaml": project.toString() });
+    }
+    const { reader, project, finish } = packageEditor(root);
+    const raw = project.toJS(), selected = providerReference(root, args.reference);
+    const name = identifier.parse(args.name ?? selected.manifest.platform);
+    const configurations = raw.providers.configurations;
+    if (configurations[name]) {
+        const existing = packageReferenceSchema.parse(raw.providers.packages[configurations[name].package]);
+        check(args.update ||
+            (friendlyReference(existing.source) === selected.source &&
+                existing.version === selected.version), "CONFLICT", `Provider configuration ${name} already exists; use provider_migrate or a different name`);
+        if (args.update) {
+            check(friendlyReference(existing.source) === selected.source, "CONFLICT", "Use plugin migrate to change provider identity");
+            project.setIn(["providers", "packages", configurations[name].package], `${selected.source}@${selected.version}`);
+            return finish({ "project.yaml": project.toString() });
+        }
+        if (existing.source !== selected.source) {
+            project.setIn(["providers", "packages", configurations[name].package], `${selected.source}@${selected.version}`);
+            return finish({ "project.yaml": project.toString() });
+        }
+        return finish({});
+    }
+    check(!raw.providers.packages[name], "CONFLICT", `Package key ${name} already exists`);
+    const environmentNames = Object.keys(raw.environments);
+    const files = providerAuthor(root, args.reference, {
+        operation: "initialise",
+        options: {
+            id: raw.id,
+            provider: args.reference,
+            environments: environmentNames,
+        },
+    }, (n) => ["project.yaml", "README.md", ".gitignore"].includes(n) ||
+        /^environments\/[\w-]+\.yaml$/.test(n));
+    const skeleton = parseDocument(files["project.yaml"]).toJS();
+    const defaults = skeleton.providers.configurations[skeleton.defaults.provider];
+    check(defaults, "PROVIDER", "Provider did not supply its default configuration");
+    project.setIn(["providers", "packages", name], `${selected.source}@${selected.version}`);
+    const bindingName = `${name}_${defaults.binding}`;
+    project.setIn(["providers", "configurations", name], {
+        ...defaults,
+        package: name,
+        binding: bindingName,
+    });
+    if (!raw.defaults?.provider)
+        project.setIn(["defaults", "provider"], name);
+    const replacements = {};
+    for (const env of environmentNames) {
+        const reference = raw.environments[env];
+        const envPath = reference.$resolve
+            ? relative(root, reader.path(reference.$resolve))
+            : undefined;
+        const current = envPath
+            ? parseDocument(reader.text(envPath))
+            : parseDocument(stringify(reference));
+        const generated = parseDocument(files[`environments/${env}.yaml`]).toJS();
+        for (const group of ["values", "bindings"])
+            for (const [originalKey, value] of Object.entries(generated[group] ?? {})) {
+                const key = group === "bindings" && originalKey === defaults.binding
+                    ? bindingName
+                    : originalKey;
+                if (current.hasIn([group, key]))
+                    check(canonical(current.toJS()[group][key]) === canonical(value), "CONFLICT", `Environment ${env} ${group}.${key} conflicts with provider defaults; configure explicitly before registration`);
+                else
+                    current.setIn([group, key], value);
+            }
+        if (envPath)
+            replacements[envPath] = current.toString();
+        else
+            project.setIn(["environments", env], current.toJS());
+    }
+    replacements["project.yaml"] = project.toString();
+    return finish(replacements);
+}
+function artifactFiles(envelope) {
+    check(envelope.apiVersion === "ingestron.provider-command-result/v1" &&
+        envelope.execution === "offline-json", "PROVIDER", "Expected an offline provider result");
+    const artifacts = envelope.result?.artifacts;
+    check(envelope.result?.apiVersion === "ingestron.artifact-proposal/v1" &&
+        artifacts &&
+        typeof artifacts === "object" &&
+        !Array.isArray(artifacts), "PROVIDER", "Provider did not return file artifacts");
+    check(Object.keys(artifacts).length > 0 && Object.keys(artifacts).length <= 200, "LIMIT", "Expected 1–200 artifacts");
+    for (const [name, text] of Object.entries(artifacts))
+        check(/^[A-Za-z0-9_-][A-Za-z0-9_.-]*\.(json|yaml|yml|sql|py|mjs|txt|md)$/.test(name) &&
+            typeof text === "string" &&
+            text.length <= 2000000, "PROVIDER", "Invalid artifact filename or content");
+    return artifacts;
+}
+export function sourcePrepare(root, environment, args) {
+    const source = sourceShow(root, args.id, environment).selected;
+    check(source.execution === "local" || source.execution === "manual", "NOT_IMPLEMENTED", "Source preparation supports manual and local execution modes only.");
+    const input = new Configuration(root).load(args.input);
+    check(!input.sourceId || input.sourceId === source.id, "SOURCE", "Reader input belongs to a different source");
+    check(!input.sourceKind || input.sourceKind === source.type, "SOURCE", "Reader input has a different source type");
+    check(!input.format || input.format === source.format, "SOURCE", "Reader input has a different format");
+    const result = runProviderCommand(root, environment, {
+        configuration: providerConfiguration(root, source.provider),
+        command: "discover source prepare",
+        input: {
+            ...input,
+            sourceId: source.id,
+            sourceKind: source.type,
+            ...(source.format ? { format: source.format } : {}),
+        },
+    });
+    const artifacts = artifactFiles(result), files = {};
+    const out = args.out ?? `discovery/${source.id}/reader`;
+    for (const [name, text] of Object.entries(artifacts)) {
+        const path = `${out}/${name}`;
+        check(!existsSync(fence(root, path)), "OWNER", `Existing reader file ${path}; choose another output directory`);
+        files[path] = text;
+    }
+    return preview(root, files);
+}
+function metadataContracts(root, environment, path, provider) {
+    const reader = new Configuration(root), metadata = reader.load(path);
+    if (metadata.kind === "DataContract") {
+        validateContract(metadata);
+        return [metadata];
+    }
+    if (metadata.columns) {
+        const proposal = contractDraft(root, path, "imported", "contracts/imported.odcs.yaml");
+        return [parseDocument(proposal.changes[0].after).toJS()];
+    }
+    const result = runProviderCommand(root, environment, {
+        configuration: providerConfiguration(root, provider),
+        command: "discover contracts",
+        input: metadata,
+    });
+    const contracts = Object.entries(artifactFiles(result))
+        .filter(([n]) => n.endsWith(".odcs.json"))
+        .map(([, text]) => JSON.parse(text));
+    check(contracts.length > 0, "METADATA", "No contracts found in metadata");
+    contracts.forEach((c) => validateContract(c));
+    return contracts;
+}
+export function sourceImport(root, environment, args) {
+    const source = sourceShow(root, args.id, environment).selected, reader = new Configuration(root);
+    const input = reader.load(args.metadata);
+    check(!input.sourceId || input.sourceId === source.id, "SOURCE", "Metadata belongs to a different source");
+    check(!input.sourceKind || input.sourceKind === source.type, "SOURCE", "Metadata has a different source type");
+    check(!input.format || input.format === source.format, "SOURCE", "Metadata has a different format");
+    const contracts = metadataContracts(root, environment, args.metadata, source.provider);
+    const path = metadataPath(source.id, environment);
+    // Replacement is a normal digest-bound authoring proposal, so --dry-run and
+    // MCP review/apply protect imported evidence just like configuration edits.
+    return preview(root, {
+        [path]: JSON.stringify({
+            apiVersion: "ingestron.discovery/v1",
+            sourceId: source.id,
+            environment,
+            sourceDigest: digest(reader.text(sourcePath(source.id))),
+            inputDigest: digest(reader.text(args.metadata)),
+            contracts,
+            evidence: "Imported metadata; source access and completeness are not verified by core",
+        }, null, 2) + "\n",
+    });
+}
+export function draftContract(root, environment, args) {
+    identifier.parse(args.id);
+    check(!!args.source !== !!args.metadata, "INPUT", "Choose exactly one of source or metadata");
+    let contracts, evidence;
+    if (args.source) {
+        const source = sourceShow(root, args.source, environment);
+        const reader = new Configuration(root), snapshot = reader.load(metadataPath(source.id, environment));
+        check(snapshot.apiVersion === "ingestron.discovery/v1" &&
+            snapshot.sourceId === source.id &&
+            snapshot.environment === environment, "METADATA", "Import discovery metadata for this source and selected environment first");
+        check(snapshot.sourceDigest === digest(reader.text(sourcePath(source.id))), "STALE", "Source configuration changed; import fresh metadata before drafting");
+        contracts = snapshot.contracts;
+        evidence = {
+            sourceId: source.id,
+            inputDigest: snapshot.inputDigest,
+            environment,
+        };
+    }
+    else {
+        contracts = metadataContracts(root, environment, args.metadata, args.provider);
+        evidence = {
+            inputDigest: digest(new Configuration(root).text(args.metadata)),
+            environment,
+        };
+    }
+    const matches = args.entity
+        ? contracts.filter((c) => c.id === args.entity ||
+            c.id.endsWith(`__${args.entity}`) ||
+            c.schema?.some((s) => s.name === args.entity || s.physicalName === args.entity))
+        : contracts;
+    check(matches.length === 1, "SELECT", "Select exactly one discovered entity with entity (contract ID or physical name)");
+    const contract = {
+        ...matches[0],
+        id: args.id,
+        name: args.id,
+        status: "draft",
+    };
+    validateContract(contract);
+    const path = args.out ?? `contracts/${args.id}.odcs.yaml`;
+    const provenance = `contracts/${args.id}.provenance.json`;
+    for (const file of [path, provenance])
+        check(!existsSync(fence(root, file)), "OWNER", `Contract output ${file} already exists; use a new ID or review the existing file`);
+    return preview(root, {
+        [path]: stringify(contract),
+        [provenance]: JSON.stringify({
+            ...evidence,
+            contract: path,
+            status: "draft",
+            review: "Review schema, keys, types and business requirements before building",
+        }, null, 2) + "\n",
+    });
+}
+export function contractPath(root, id) {
+    if (/\.(json|ya?ml)$/.test(id)) {
+        fence(root, id);
+        return id;
+    }
+    return `contracts/${identifier.parse(id)}.odcs.yaml`;
+}
+export function contractList(root) {
+    const dir = fence(root, "contracts");
+    return existsSync(dir)
+        ? readdirSync(dir)
+            .filter((n) => /\.odcs\.(json|ya?ml)$/.test(n))
+            .sort()
+            .map((n) => {
+            const path = `contracts/${n}`, contract = new Configuration(root).load(path);
+            validateContract(contract, path);
+            return {
+                id: contract.id,
+                status: contract.status,
+                path,
+                entities: contract.schema?.map((s) => s.physicalName ?? s.name) ?? [],
+            };
+        })
+        : [];
+}
+export function flowCreate(root, environment, args) {
+    const { contract: selectedContract, source: selectedSource, ...options } = args;
+    let sourceId = selectedSource;
+    if (!sourceId &&
+        selectedContract &&
+        /^[A-Za-z_][\w-]*$/.test(selectedContract)) {
+        const provenance = fence(root, `contracts/${selectedContract}.provenance.json`);
+        if (existsSync(provenance))
+            sourceId = JSON.parse(readFileSync(provenance, "utf8")).sourceId;
+    }
+    if (sourceId) {
+        const source = sourceShow(root, sourceId, environment).selected;
+        options.sourceKind ??= source.type;
+        options.format ??= source.format;
+        options.sourceBinding ??= source.binding;
+        options.provider ??= source.provider;
+    }
+    if (options.provider)
+        options.provider = providerConfiguration(root, options.provider);
+    const proposal = addFlow(root, options);
+    if (!selectedContract)
+        return proposal;
+    check(options.kind === "ingestion", "INPUT", "Use flow output add to bind a transformation's producing port and output contract");
+    const path = contractPath(root, selectedContract), contract = new Configuration(root).load(path);
+    contractColumns(contract, path);
+    const tableId = identifier.parse(contract.id);
+    const replacements = Object.fromEntries(proposal.changes.map((c) => [c.path, c.after]));
+    const file = `flows/${options.id}/flow.yaml`, doc = parseDocument(replacements[file]);
+    const relativeContract = relative(dirname(resolve(root, file)), resolve(root, path)).replaceAll("\\", "/");
+    doc.setIn(["tables", tableId], { contract: { $resolve: relativeContract } });
+    replacements[file] = doc.toString();
+    return preview(root, replacements);
+}

package/dist/plugins/authoring.d.ts

@@ -0,0 +1,88 @@
+export declare function providerReference(root: string, reference: string): {
+    file: string;
+    root: string;
+    entry: {
+        repository: string;
+        path: string;
+        commit: string;
+        files: Record<string, string>;
+    };
+    manifest: {
+        apiVersion: "ingestron.provider/v1";
+        id: string;
+        version: string;
+        platform: string;
+        activities: Record<string, string>;
+        capabilities?: {
+            artifactKinds: string[];
+            delivery: boolean;
+            handovers: ("files" | "relation")[];
+            packContracts: Record<string, {
+                version: string;
+                activities: string[];
+            }>;
+        } | undefined;
+        projectAssembly?: {
+            apiVersion: "ingestron.project-assembly/v1";
+            command: string;
+        } | undefined;
+        connectorRuntimes?: Record<string, {
+            selectionSchema: Record<string, unknown>;
+            executionSchema: Record<string, unknown>;
+            prepareCommand: string;
+            contractsCommand?: string | undefined;
+            executionPlatforms: string[];
+        }> | undefined;
+        configurationSchema?: string | Record<string, unknown> | undefined;
+        standards?: {
+            id: string;
+            description: string;
+            sourceKinds?: string[] | undefined;
+            dataFlow?: "forbidden" | "required" | undefined;
+        }[] | undefined;
+        compatibility?: {
+            plan: "ingestron.plan/v1";
+            requiredFeatures: string[];
+            minimumCli: string;
+        } | undefined;
+        outputSchemas?: Record<string, string> | undefined;
+        lifecycle?: {
+            apiVersion: "ingestron.provider-lifecycle/v1";
+            module: string;
+        } | undefined;
+        planner?: {
+            apiVersion: "ingestron.provider-planning/v1";
+            module: string;
+        } | undefined;
+        commands?: {
+            apiVersion: "ingestron.provider-commands/v1";
+            namespace?: string | undefined;
+            execution: "offline-json";
+            module: string;
+            definitions: {
+                name: string;
+                description: string;
+                reportPack?: boolean | undefined;
+                examples?: string[] | undefined;
+                resultSchema?: Record<string, unknown> | undefined;
+                inputSchema: Record<string, unknown>;
+            }[];
+        } | undefined;
+        execution?: {
+            apiVersion: "ingestron.execution/v1";
+            transport: string;
+            entryPoint: string;
+            actions: ("approve" | "discover" | "prepare" | "review" | "run")[];
+            status: "receipt";
+            retry: "same-run-id";
+            cancellation: "interrupt";
+        } | undefined;
+        renderer?: {
+            apiVersion: "ingestron.provider-generation/v1";
+            module: string;
+        } | undefined;
+    };
+    source: string;
+    version: string;
+};
+export declare function providerAuthor(root: string, reference: string, input: Record<string, unknown>, allowed: (name: string) => boolean): Record<string, string>;

package/dist/plugins/authoring.js

@@ -0,0 +1,34 @@
+import { friendlyReference } from "../core/package-references.js";
+import { readFileSync } from "node:fs";
+import { resolve, dirname, relative } from "node:path";
+import { canonicalPackageReference, resolvePackage, providerPackageSchema, packageYaml, fence, } from "../core/packages.js";
+import { check, isMap } from "../core/errors.js";
+import { executeProvider } from "./provider-renderer.js";
+import { checkProviderCompatibility } from "./compatibility.js";
+export function providerReference(root, reference) {
+    const canonical = canonicalPackageReference(reference), at = canonical.lastIndexOf("@");
+    const pkg = resolvePackage(root, canonical), manifest = providerPackageSchema.parse(packageYaml(pkg.file));
+    checkProviderCompatibility(manifest);
+    return {
+        ...pkg,
+        manifest,
+        source: friendlyReference(canonical.slice(0, at)),
+        version: canonical.slice(at + 1),
+    };
+}
+export function providerAuthor(root, reference, input, allowed) {
+    const selected = providerReference(root, reference);
+    check(selected.manifest.lifecycle, "PROVIDER", "This provider does not declare lifecycle authoring; select a migrated version");
+    const file = fence(selected.root, relative(selected.root, resolve(dirname(selected.file), selected.manifest.lifecycle.module)));
+    const result = executeProvider(readFileSync(file, "utf8"), {
+        apiVersion: "ingestron.provider-authoring/v1",
+        ...input,
+        provider: { source: selected.source, version: selected.version },
+    }, false, "author");
+    check(isMap(result.files) && Object.keys(result).length === 1, "PROVIDER", "Invalid authoring response");
+    for (const [name, value] of Object.entries(result.files)) {
+        fence(root, name);
+        check(allowed(name) && typeof value === "string" && value.length <= 1000000, "PROVIDER", `Invalid authored file ${name}`);
+    }
+    return result.files;
+}

package/dist/plugins/compatibility.d.ts

@@ -0,0 +1,23 @@
+/** All provider entry points use one legacy ABI check. App semver resets must
+ * not make authoring work while planning or command dispatch rejects the package. */
+export declare const hostFeatures: string[];
+export declare function checkPluginCompatibility(minimum?: string, requiredFeatures?: string[]): void;
+/** Capability opt-ins must also declare the host protocol features they need. */
+export declare function checkProviderCompatibility(manifest: {
+    compatibility?: {
+        minimumCli: string;
+        requiredFeatures?: string[];
+    };
+    projectAssembly?: unknown;
+    execution?: unknown;
+    connectorRuntimes?: Record<string, unknown>;
+    capabilities?: {
+        artifactKinds: string[];
+        delivery: boolean;
+        handovers: string[];
+        packContracts: Record<string, {
+            version: string;
+            activities: string[];
+        }>;
+    };
+}): void;

package/dist/plugins/compatibility.js

@@ -0,0 +1,55 @@
+import { pluginCompatibilityVersion } from "../version.js";
+import { check } from "../core/errors.js";
+/** All provider entry points use one legacy ABI check. App semver resets must
+ * not make authoring work while planning or command dispatch rejects the package. */
+export const hostFeatures = [
+    "project-assembly",
+    "provider-execution",
+    "connector-runtime-capabilities",
+    "connector-runtime-assets",
+    "project-connections",
+    "odcs-connections",
+    "report-packs",
+    "native-project",
+    "extension-packs",
+    "delivery-exports",
+    "relation-handovers",
+    "export-groups",
+    "model-inputs",
+    "ingestion-presets",
+];
+export function checkPluginCompatibility(minimum, requiredFeatures = []) {
+    for (const feature of requiredFeatures)
+        check(hostFeatures.includes(feature), "COMPATIBILITY", `Unsupported provider host feature ${feature}`);
+    if (!minimum)
+        return;
+    const current = pluginCompatibilityVersion.split(".").map(Number);
+    const required = minimum.split(".").map(Number);
+    check((current
+        .map((value, index) => value - required[index])
+        .find((value) => value !== 0) ?? 0) >= 0, "COMPATIBILITY", `Provider requires plugin compatibility ${minimum}; this host supports ${pluginCompatibilityVersion}`);
+}
+/** Capability opt-ins must also declare the host protocol features they need. */
+export function checkProviderCompatibility(manifest) {
+    const required = manifest.compatibility?.requiredFeatures ?? [];
+    check(!manifest.execution || required.includes("provider-execution"), "COMPATIBILITY", "Execution providers must declare requiredFeatures provider-execution");
+    checkPluginCompatibility(manifest.compatibility?.minimumCli, required);
+    if (manifest.connectorRuntimes &&
+        Object.keys(manifest.connectorRuntimes).length)
+        check(required.includes("connector-runtime-capabilities"), "COMPATIBILITY", "Provider must declare requiredFeatures: connector-runtime-capabilities");
+    if (manifest.projectAssembly)
+        check(required.includes("project-assembly"), "COMPATIBILITY", "Provider must declare requiredFeatures: project-assembly");
+    const c = manifest.capabilities;
+    if (!c)
+        return;
+    const needed = [
+        ...(c.artifactKinds.some((k) => !["native-notebook", "native-pipeline"].includes(k))
+            ? ["native-project"]
+            : []),
+        ...(c.delivery ? ["delivery-exports"] : []),
+        ...(c.handovers.includes("relation") ? ["relation-handovers"] : []),
+        ...(Object.keys(c.packContracts).length ? ["extension-packs"] : []),
+    ];
+    for (const feature of needed)
+        check(required.includes(feature), "COMPATIBILITY", `Provider must declare requiredFeatures: ${feature}`);
+}

package/dist/plugins/generation.d.ts

@@ -0,0 +1,5 @@
+import type { Plan } from "../core/schema.js";
+export declare function validateProviderPlan(plan: Plan): void;
+export declare function generateProvider(root: string, plan: Plan): Record<string, string>;
+/** The same provider schema gate applies after native rendering and project assembly. */
+export declare function validateProviderFiles(code: string, schemas: Record<string, string>, files: Record<string, string>): void;