@ingestron/core 0.12.1 → 0.12.3

package/README.md

@@ -9,8 +9,8 @@ connector runtime assets and standards through explicit package references.
 
 ## Use the library
 
-Requires Node 22.12 or newer for runtime operations. The npm package name is `@ingestron/core`;
-initial registry publication is pending. To build the public source checkout:
+Requires Node 22.12 or newer for runtime operations. The npm package name is
+`@ingestron/core`. To build the public source checkout:
 
 ```sh
 pnpm install --frozen-lockfile
@@ -36,6 +36,14 @@ project through a reviewed change proposal. It needs no provider, cloud account
 source data. Building native assets requires an installed provider and configured
 flows.
 
+In a project, `packages` maps short names to exact installed releases. The
+`packages.lock.yaml` file retains each full repository reference, commit and
+file hashes. An ingestion connection holds endpoint and authentication settings;
+each `flow.tables` entry selects one physical source object and its ODCS contract
+selects the output columns. Connector packages define the allowed table source
+shape, so the same project layout works across source types. Older stream-based
+connector releases remain supported.
+
 ## Integration guides
 
 - [Operation and editor API](docs/api.md): requests, results, permissions, errors

package/THIRD_PARTY_NOTICES.md

@@ -640,7 +640,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
-### yaml@2.9.0
+### yaml@2.9.1
 
 Declared licence: ISC
 
@@ -662,7 +662,7 @@ TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
 THIS SOFTWARE.
 ```
 
-### zod@4.5.4
+### zod@4.6.5
 
 Declared licence: MIT
 

package/dist/compiler-fingerprint.json

@@ -3,15 +3,15 @@
     "dist/assets/schemas/ODCS-LICENSE": "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4",
     "dist/assets/schemas/odcs-3.1.0.json": "1a35de14c688b400fef306564f66e2af3304f057cd5cd6e7b847c1a8bf252c5b",
     "dist/assets/schemas/provenance.json": "4b5eb1fd89b81223f7946113b651d5a3a18adaa28948e43c3615dd851fb6844e",
-    "dist/core/authoring.js": "43025703f23b61090d1ea6912e387e5ed74a93568f068339f9a7ecae88795a51",
+    "dist/core/authoring.js": "405c818184960c93a0cd0c041af2d415d56f62670ff91b0fb5f0d2aeed1feb9b",
     "dist/core/config.js": "b7e7138f7cc4a7b4ec8f6d0f0616c8802f2d802ec29aa09b40c1fc5c9324e016",
-    "dist/core/connections.js": "bd351bcb05275321078409b4de83648751a51e609ab5c5fc5489f1fe31433bcd",
-    "dist/core/connector-package.js": "c1d39fce629a524fa199ed5d0dffe6a36c500e1018fbb8379d700330372b46a7",
+    "dist/core/connections.js": "37b797b402788e00c51f3cac93b87342d158ed9b279753db91006d2d6c66bb4a",
+    "dist/core/connector-package.js": "de9729e9e4b0cf05bd1ef347e57ffd489245bb68efce5c313ccba72b78409f41",
     "dist/core/contracts.js": "a1b7fd28f776117cca86a25c6c70e852ff57ffea2bb9e7accbf2d583948d9dde",
     "dist/core/deliveries.js": "a4d2cb1213bc4c02cffb962dcb943ba98e261d37cfb21041948ec637599db080",
     "dist/core/delivery-exports.js": "d895b044c08f2059f0275724205120c72dd4bf5b74170bb01bdf42dd9d526d56",
     "dist/core/development.js": "2b55b15d545172e527cf66868d96d97c5ca081d0a83892ffd253eadaa3cc1b39",
-    "dist/core/ecosystem-authoring.js": "782f20a08408af1c3c93ab27b521a86f2d6cddac042c2503cb58c4a76fdcd6fc",
+    "dist/core/ecosystem-authoring.js": "4320560eac2d2060e9e20be6a097759512c709a04fb7dc0520147ecd5ff6655e",
     "dist/core/errors.js": "8117e35fba84ae34627cb7d3bef46aaf6d8718c512140fa0ab08ccbdeeeec8c3",
     "dist/core/execution.js": "496807e7428528e31e76d51144dfd84682d435467b30a35574310af525ddeca7",
     "dist/core/extension-packs.js": "6b2aaa83e51f40e176cc4cfed574a4a17646bb3f526666fe8e0456d2912a8045",
@@ -21,16 +21,17 @@
     "dist/core/installed-plugins.js": "817ed411aef6f5b966a1828893081406805d2c8764d2ca20fd7e250e8a2168a8",
     "dist/core/model-pack-schema.js": "e3eb7ff33ddc652643e3f896637de0034004cd0cf26b0e296a074f830ae0b870",
     "dist/core/model-packs.js": "fee776ea0804dc66c9f140e57d94a3922d69c52d03c72079842ec43417616b0d",
-    "dist/core/operations.js": "bd6217f7eb33c3c5649f8edecab3ce87d4774c9ff790feff8763ebab71866531",
+    "dist/core/operations.js": "7f4a9eeee19d3e1e4c1beecc0350e38d386f012edfb31c3248efcd22ebd40a77",
     "dist/core/package-references.js": "bd3085eb6dcdac399d79af109d0a9e710a0532eba61e5298dc842aec9c7ef10a",
-    "dist/core/packages.js": "9c699b518a5c364c361d2b856f3fc6e67fe43ce0dc906b8aa474e341c5e49110",
-    "dist/core/planner.js": "f91902f4c37a7588965360fcddbda79301b59a0b66ef2f70c0378fa5dfcc7088",
-    "dist/core/project-build.js": "1f1002b4f6c506986c5aa6a5bb01ad5f3b4658a7a1319b65d79eaa67916fb994",
-    "dist/core/provider-commands.js": "8bd82821f6ed0eefce8216e7c03c271f28cb9f4bfda7724d5c1de6be1855e535",
+    "dist/core/packages.js": "6af57d7f2b3d78837a39cf9b14a5d8151a6825dfce359680382fd8096a08d259",
+    "dist/core/planner.js": "974c6bac5c533a32a7c45f797ef4d857c644448aa243a929caca5917fb9f3fb8",
+    "dist/core/project-build.js": "18ffe962068967af255e77f1dc48fa4dd9161cd50659a8a3d9ac3b161856082e",
+    "dist/core/project-packages.js": "b031dd9e3c5c147e8e1ed589b5eab21b9067acbefc1d4cd1dc5b6b7018cc39cf",
+    "dist/core/provider-commands.js": "4f9b1565b3252a8c9c49a19a69b92fb6a72cc800cadc3e97812bf88c7e808466",
     "dist/core/provider-starter.js": "69795c1b79360e48664e91db0768f813fe4efc91aede003e1bf032f71731754c",
     "dist/core/report-pack-schema.js": "fe8ecdc2b8deacd8b2a1e46588ee06744a7b6d8e7342786e320f74cc848665fa",
-    "dist/core/schema.js": "4cbad607f372584fe83f44a121bd978dea7529db5c1eb51168dcd62812c2eeab",
-    "dist/core/workflows.js": "1a5fe93b34d963efb07ab1f67641106386fa3ef9d9e80bd3e59c13795925fda6",
+    "dist/core/schema.js": "821e79cfc56dbd8c206959c53c0cda6d81507ae78010da1ec614e204c17d96eb",
+    "dist/core/workflows.js": "e0b9e34fdd9b3f56403e8beb58e2b0bfbc0604beccb3113fc529c460817bc4d4",
     "dist/plugins/authoring.js": "ff985a7173c7aeda4a431a8603a4ab8631dc5134486578ede7d1301ebc3e6a19",
     "dist/plugins/compatibility.js": "a6591cfa4ca5a324fd29856e51319e39be470d6ed835ee268b293727ce11f8b7",
     "dist/plugins/generation.js": "7b0bae4de23edab4c2596d1f8ed2244d70b30fcae60395994b3964ffc845e9d5",
@@ -42,15 +43,15 @@
     "dist/version.js": "48af2aa1e425f1e387c082bbf0ad2c0c8d757c468101a614c3864153a94e6889"
   },
   "sources": {
-    "src/core/authoring.ts": "fe80e823cfb82b39894aac9c5f733d489241b4a22bed278079254acff45a0aca",
+    "src/core/authoring.ts": "e1f02cf6c50cda20a62c1ea318908854939ab5be7da7de829350c7e11788be01",
     "src/core/config.ts": "f282eb246438608e1951556dfeab9372daf65330a15a9d159d36d1f940370344",
-    "src/core/connections.ts": "19327f428382189a73a462cfd0b48943c0ba3b000633412b35da1d2ded81868b",
-    "src/core/connector-package.ts": "f302432c3954a6230ddf02e3ae796c0a641e52984c0db3bfbfc10b3d5539e49e",
+    "src/core/connections.ts": "dbdaca4193efa203cffa02fd819b95f82bbd604a7678ba7dc6ba065205c49ce7",
+    "src/core/connector-package.ts": "a36151f6ffb49836547984eae871023ad1ad69a136f33cd6ad608496f84c85f8",
     "src/core/contracts.ts": "b7445086085b17d5ae8d5a7f4e2e849f286948e1a2a146ceb79660846e8616e5",
     "src/core/deliveries.ts": "6be0a7059c057420ba22a5515703164a892fac9e79a5bdb0e0871ea0b92ddd15",
     "src/core/delivery-exports.ts": "45a4d13e73a3809340fcd0f018dd06e2e360c67c1a117c672cd48be463c82d58",
     "src/core/development.ts": "decd47d8f6ca3289fea45331f27b99b0feb7188ae0a9e152c6459cc00658e7bd",
-    "src/core/ecosystem-authoring.ts": "4c4385f2c9a3208d32e425183555916742a856dc6cc1bb44a806e94bb7537cba",
+    "src/core/ecosystem-authoring.ts": "61a44100843273e74b385704195b5e36a72afb9482f910eaacdcf3abda7be38e",
     "src/core/errors.ts": "55e7ec3239bb3bcae73cf37e700cd83b9ea3336bf5514062827a3627a606977d",
     "src/core/execution.ts": "44ebbe7b6f64e0c3c224dd6f419939e500de92b7e4e8b283b0b33266e1d1fbf1",
     "src/core/extension-packs.ts": "76671a6971598212c9ec0bb0ce9b75feee13dec09565fa0adc9f050a6ae668ec",
@@ -60,16 +61,17 @@
     "src/core/installed-plugins.ts": "951d15cdd8ca4a2c7d97fb01a46838822fe1b2fcf083ff8cf4bdca20d0997a2d",
     "src/core/model-pack-schema.ts": "bc9b30ab257fd25766cba63aa2fb6891c05e4b3eccf56d820caaab2dcc4147b4",
     "src/core/model-packs.ts": "a110d319f6feeff22a2d0d3a99ce5e49e56817d0cc27ab77d831d04a945ddfd3",
-    "src/core/operations.ts": "3f63b1a7bab027c81a8b27dc31094910df34af6ea333b5f12590b9cf85904cb4",
+    "src/core/operations.ts": "e0a5a0e869e96de4e869f89e0fd794cb9fa537a16fb1f37fd8cf2b7ca777c08d",
     "src/core/package-references.ts": "5c5cee7e140158928e2e5a37f426520c7c2f042546a37eed4507d79326181f5a",
-    "src/core/packages.ts": "b32d52adf6d4c3673cc70b5bc8638e5986fe4790b9e9ac386e057561cec13b32",
-    "src/core/planner.ts": "498f5405f3088ee6d54ec8ab4a458813757697c150a56eab33f547aebb214da1",
-    "src/core/project-build.ts": "feb0fe50aff7b1fbdc8d96bcdb177a72a412639d1af98c3cff3b010de90a6428",
-    "src/core/provider-commands.ts": "f8a045230f61be0273910276b51e5c2e4bc0659f34c8a9361a38ab292c39eb4c",
+    "src/core/packages.ts": "5a8ac2c2c2b5ac70c97339d7d5b9d76ac44422566c1dcbb780323de512905fd4",
+    "src/core/planner.ts": "2c6f0d53e21cbb60fc2433e7da1245707133336274c60b9a5678614dabf09bca",
+    "src/core/project-build.ts": "7fa5038e7e2ff2625a30ffae282369954a5989347c6435849b72c95f2e52e247",
+    "src/core/project-packages.ts": "4c5cb98aeb5030db7cf2c851cd9e40ed9aae038517fba2d8d7159e884f08b7a0",
+    "src/core/provider-commands.ts": "195133079085aae57208bee607af439d0ea09456d526e27ec73bfdc9d727805f",
     "src/core/provider-starter.ts": "eeb504e347638bb933d204dd4d5a7e3e94ff45db136c5edd3fb457061342e405",
     "src/core/report-pack-schema.ts": "cf2c68f3725cef847627ce61acd0887f04d0067bc324841d8a552bcb12d274b0",
-    "src/core/schema.ts": "dc1c5464878916bbdee08662320310bb202a21ebfca9e534a30746603c9aa46f",
-    "src/core/workflows.ts": "b8afae8637eb92b58ab41a41fc245950e1c8e8820a6a27358508ae54c04c7a78",
+    "src/core/schema.ts": "a99a90e51be10ed56713573df6f238e6aca5b897a9679fe7bd2a8c0ad1e7f586",
+    "src/core/workflows.ts": "f9e8d7f0a3841b5e385a5279e202f5a3334972bb549c8c85f01e7cfbb4e16f25",
     "src/plugins/authoring.ts": "a0d68d406b4569c0b48eec458407d24c3d4eeed5b7918c6c4fcb3828ada93fe5",
     "src/plugins/compatibility.ts": "b5d357a1dc2a972cf8209311602f9fd816ba0a59cbe747f86f1b5567754073ea",
     "src/plugins/generation.ts": "a495906af09cf7bf820c7aba390bf742d7e94328ce708a2ff40f613f451fe237",

package/dist/core/authoring.js

@@ -5,6 +5,8 @@ import { resolve, dirname, relative } from "node:path";
 import { parseDocument, stringify } from "yaml";
 import { check, digest, canonical, merge, Problem } from "./errors.js";
 import { Configuration } from "./config.js";
+import { projectSchema } from "./schema.js";
+import { projectPackages } from "./project-packages.js";
 import { contractColumns } from "./contracts.js";
 import { fence, installedProviders, canonicalPackageReference, } from "./packages.js";
 const yaml = (text, file) => {
@@ -186,7 +188,7 @@ export function addFlow(root, options) {
     const configuration = options.provider ?? resolved.defaults.provider;
     const config = resolved.providers.configurations[configuration];
     check(config, "PROVIDER", "Select a provider configuration for this flow");
-    const pkg = resolved.providers.packages[config.package];
+    const pkg = projectPackages(projectSchema.parse(resolved))[config.package];
     const environments = Object.values(raw.environments).map((ref) => {
         check(ref.$resolve, "AUTHORING", "Keep editable environments in referenced files");
         const file = reader.path(ref.$resolve);

package/dist/core/connections.js

@@ -2,12 +2,14 @@ import { readFileSync } from "node:fs";
 import { fence } from "./packages.js";
 import { connectorPackageSchema } from "./connector-package.js";
 import { contractColumns } from "./contracts.js";
+import { resolveModelContracts } from "./model-packs.js";
 /** Project-owned configuration; schemas and runtime assets remain plugin-owned. */
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { Configuration } from "./config.js";
 import { projectSchema, flowSchema } from "./schema.js";
+import { projectPackages } from "./project-packages.js";
 import { canonical, check, digest, isMap } from "./errors.js";
-import { canonicalPackageReference, resolvePackage, packageYaml, providerPackageSchema, } from "./packages.js";
+import { configuredPackageReference, resolvePackage, packageYaml, providerPackageSchema, } from "./packages.js";
 import { checkProviderCompatibility } from "../plugins/compatibility.js";
 import { runProviderCommand, validateSchemaShape, } from "./provider-commands.js";
 function validate(schema, value, label) {
@@ -24,6 +26,7 @@ export function prepareConnection(root, environment, flowId, validateOnly = fals
     check(profile, "ENVIRONMENT", `Unknown environment ${environment}`);
     check(!profile.environment || profile.environment === environment, "ENVIRONMENT", "Environment name differs from selected profile");
     const flows = project.flows.map((f) => reader.parse(flowSchema, f));
+    resolveModelContracts(reader, project, flows);
     check(new Set(flows.map((f) => f.id)).size === flows.length, "FLOW", "Duplicate flow IDs");
     const flow = flows.find((f) => f.id === flowId);
     check(flow && flow.kind === "ingestion" && !flow.steps, "FLOW", "Select an ingestion flow");
@@ -35,17 +38,18 @@ export function prepareConnection(root, environment, flowId, validateOnly = fals
     check(connection, "CONNECTION", "Unknown ingestion connection");
     const configured = project.providers.configurations[flow.provider ?? project.defaults.provider ?? ""];
     check(configured, "PROVIDER", "Select the execution provider configuration");
-    const owner = project.providers.packages[connection.package];
-    const executor = project.providers.packages[configured.package];
+    const packages = projectPackages(project);
+    const owner = packages[connection.package];
+    const executor = packages[configured.package];
     check(owner && executor, "PACKAGE", "Unknown connection/execution package");
     const load = (pkg) => {
-        const ref = canonicalPackageReference(`${pkg.source}@${pkg.version}`);
+        const ref = configuredPackageReference(pkg);
         const locked = resolvePackage(root, ref);
         const manifest = providerPackageSchema.parse(packageYaml(locked.file));
         checkProviderCompatibility(manifest);
         return { ref, locked, manifest };
     };
-    const sourceRef = canonicalPackageReference(`${owner.source}@${owner.version}`);
+    const sourceRef = configuredPackageReference(owner);
     const sourceLock = resolvePackage(root, sourceRef);
     const sourceRaw = packageYaml(sourceLock.file);
     check(sourceRaw.apiVersion === "ingestron.connector/v1", "CONNECTION", "Select an independently installed source connector package");
@@ -86,15 +90,22 @@ export function prepareConnection(root, environment, flowId, validateOnly = fals
     check(flow.tables && Object.keys(flow.tables).length > 0, "CONNECTION", "Select at least one table with an ODCS contract");
     const streams = new Set();
     const tables = Object.fromEntries(Object.entries(flow.tables).map(([name, table]) => {
-        check(Object.keys(table.source).length === 1 &&
-            typeof table.source.stream === "string", "CONNECTION", `${name}: source must identify one connector stream`);
-        check(!streams.has(table.source.stream), "CONNECTION", "Duplicate source stream");
-        streams.add(table.source.stream);
+        const source = descriptor.tableSourceSchema
+            ? { ...table.source, stream: name }
+            : table.source;
+        if (descriptor.tableSourceSchema)
+            validate(descriptor.tableSourceSchema, table.source, `${name} source`);
+        else
+            check(Object.keys(table.source).length === 1 &&
+                typeof table.source.stream === "string", "CONNECTION", `${name}: source must identify one connector stream`);
+        check(typeof source.stream === "string", "CONNECTION", `${name}: invalid source stream`);
+        check(!streams.has(source.stream), "CONNECTION", "Duplicate source stream");
+        streams.add(source.stream);
         check(!table.ingestion && !Object.keys(table.steps).length, "CONNECTION", "Connection tables do not accept ingestion/step overrides");
         return [
             name,
             {
-                source: table.source,
+                source,
                 contract: table.contract,
                 columns: contractColumns(table.contract),
             },

package/dist/core/connector-package.d.ts

@@ -29,6 +29,7 @@ export declare const connectorPackageSchema: z.ZodObject<{
     definition: z.ZodObject<{
         settingsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         selectionSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        tableSourceSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strict>;
     execution: z.ZodRecord<z.ZodString, z.ZodObject<{
         modes: z.ZodArray<z.ZodString>;

package/dist/core/connector-package.js

@@ -31,7 +31,11 @@ export const connectorPackageSchema = z
     })
         .strict(),
     definition: z
-        .object({ settingsSchema: schema, selectionSchema: schema })
+        .object({
+        settingsSchema: schema,
+        selectionSchema: schema,
+        tableSourceSchema: schema.optional(),
+    })
         .strict(),
     execution: z.record(z.string(), z
         .object({

package/dist/core/ecosystem-authoring.js

@@ -4,6 +4,7 @@ import { Configuration } from "./config.js";
 import { preview } from "./authoring.js";
 import { check } from "./errors.js";
 import { projectSchema } from "./schema.js";
+import { projectPackages } from "./project-packages.js";
 import { extensionPackSchema, packageYaml, resolvePackage, providerPackageSchema, } from "./packages.js";
 import { extensionActivities } from "./extension-packs.js";
 import { checkProviderCompatibility } from "../plugins/compatibility.js";
@@ -31,7 +32,7 @@ export function configurePack(root, args) {
     const configuration = project.providers.configurations[args.provider];
     check(configuration, "PROVIDER", "Unknown provider configuration");
     check(!project.providers.packs[args.name], "PACK", "Pack name already exists");
-    const pkg = project.providers.packages[configuration.package];
+    const pkg = projectPackages(project)[configuration.package];
     const file = pkg.source.startsWith(".")
         ? reader.path(pkg.source)
         : resolvePackage(root, `${pkg.source}@${pkg.version}`).file;

package/dist/core/operations.d.ts

@@ -261,6 +261,10 @@ export declare const operationSchemas: {
     }, z.core.$strict>;
     readonly packages_install: z.ZodObject<{
         reference: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            connector: "connector";
+            provider: "provider";
+        }>>;
         fromGit: z.ZodOptional<z.ZodString>;
         update: z.ZodOptional<z.ZodBoolean>;
         frozen: z.ZodOptional<z.ZodBoolean>;

package/dist/core/operations.js

@@ -259,6 +259,7 @@ export const operationSchemas = {
     packages_install: z
         .object({
         reference: z.string(),
+        kind: z.enum(["provider", "connector"]).optional(),
         fromGit: z.string().optional(),
         update: z.boolean().optional(),
         frozen: z.boolean().optional(),

package/dist/core/packages.d.ts

@@ -180,6 +180,10 @@ export declare function fence(root: string, name: string): string;
 export declare function packageYaml(file: string): any;
 /** Stable convenience names; locks always retain the explicit repository and path. */
 export declare function canonicalPackageReference(reference: string): string;
+export declare function configuredPackageReference(pkg: {
+    source: string;
+    version: string;
+}): string;
 export declare function packageLock(root: string): {
     apiVersion: "ingestron.packages-lock/v1";
     packages: Record<string, {
@@ -206,6 +210,7 @@ export declare function installPackage(root: string, reference: string, options?
     update?: boolean;
     frozen?: boolean;
     tagPrefix?: string;
+    kind?: "provider" | "connector";
 }): {
     repository: string;
     path: string;

package/dist/core/packages.js

@@ -276,6 +276,12 @@ export function canonicalPackageReference(reference) {
     check(repository.includes("/"), "PACKAGE", "Unknown plugin name; use an explicit owner/repository@version");
     return `${repository}/plugin/provider.yaml@${short[2]}`;
 }
+export function configuredPackageReference(pkg) {
+    const reference = `${pkg.source}@${pkg.version}`;
+    return /^[a-z][a-z0-9-]*@(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(reference)
+        ? reference
+        : canonicalPackageReference(reference);
+}
 const parseReference = (reference) => {
     check(!reference.endsWith("@latest"), "PACKAGE", "@latest is not supported: packages must be pinned to an exact semantic version or commit. Use plugin_versions with an explicit repository to inspect available versions.");
     const m = /^([\w.-]+\/[\w.-]+)\/(.+\.ya?ml)@(v1|(?:0|[1-9]\d*)\.\d+\.\d+|[a-f0-9]{40})$/.exec(reference);
@@ -302,6 +308,18 @@ export function packageLock(root) {
         };
 }
 export function resolvePackage(root, reference) {
+    if (/^[a-z][a-z0-9-]*@(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(reference)) {
+        const [name, version] = reference.split("@");
+        const matches = Object.keys(packageLock(root).packages).filter((lockedReference) => {
+            const installed = resolvePackage(root, lockedReference);
+            const manifest = packageYaml(installed.file);
+            return manifest.id === name && manifest.version === version;
+        });
+        check(matches.length === 1, "PACKAGE", matches.length
+            ? `Ambiguous installed package ${reference}; use an explicit reference`
+            : `Install ${reference} before building this project`);
+        return resolvePackage(root, matches[0]);
+    }
     reference = canonicalPackageReference(reference);
     const parsed = parseReference(reference), entry = packageLock(root).packages[reference];
     check(entry &&
@@ -388,13 +406,19 @@ export function installPackage(root, reference, options = {}) {
     check(!options.frozen || previous, "PACKAGE", "Frozen install requires an existing lock entry");
     if (previous &&
         !options.update &&
-        existsSync(resolve(root, `.ingestron/packages/${digest(previous.repository)}/${previous.commit}`)))
+        existsSync(resolve(root, `.ingestron/packages/${digest(previous.repository)}/${previous.commit}`))) {
+        if (options.kind) {
+            const installed = resolvePackage(root, reference);
+            const manifest = packageYaml(installed.file);
+            check(manifest.apiVersion === `ingestron.${options.kind}/v1`, "PACKAGE", `Expected a ${options.kind} package at ${reference}`);
+        }
         return {
             reference,
             ...resolvePackage(root, reference).entry,
             cached: true,
             informationFile: savePluginInformation(root, reference),
         };
+    }
     const control = fence(root, ".ingestron");
     mkdirSync(control, { recursive: true });
     const guard = resolve(control, "package-install.lock");
@@ -472,6 +496,8 @@ export function installPackage(root, reference, options = {}) {
             files[m[5]] = digest(text);
         }
         const manifest = packageYaml(fence(staged, parsed.path));
+        if (options.kind)
+            check(manifest.apiVersion === `ingestron.${options.kind}/v1`, "PACKAGE", `Expected a ${options.kind} package at ${reference}`);
         if (manifest.apiVersion === "ingestron.connector/v1") {
             const connector = connectorPackageSchema.parse(manifest);
             check(connector.upstream.licenceStatus === "evidenced", "LICENCE", "Connector licence evidence is missing or conflicting; installation held");

package/dist/core/planner.d.ts

@@ -17,6 +17,10 @@ export declare function inspectProject(root: string, environment?: string, optio
         apiVersion: "ingestron.project/v1";
         id: string;
         description?: string | undefined;
+        packages: Record<string, {
+            source: string;
+            version: string;
+        }>;
         defaults: {
             provider?: string | undefined;
             naming: {

package/dist/core/planner.js

@@ -6,6 +6,7 @@ import addFormats from "ajv-formats";
 import { resolve, relative, dirname } from "node:path";
 import { Configuration } from "./config.js";
 import { projectSchema, flowSchema, stepSchema, } from "./schema.js";
+import { projectPackages } from "./project-packages.js";
 import { check, canonical, digest, isMap, merge, Problem } from "./errors.js";
 import { executeProvider } from "../plugins/provider-renderer.js";
 import { contractColumns } from "./contracts.js";
@@ -115,7 +116,7 @@ function provider(project, bindings, reader, selected) {
     check(name, "PROVIDER", "Select a provider or set defaults.provider");
     const configured = project.providers.configurations[name];
     check(configured, "PROVIDER", `Unknown provider configuration ${name}`);
-    const pkg = project.providers.packages[configured.package];
+    const pkg = projectPackages(project)[configured.package];
     check(pkg, "PROVIDER", `Unknown provider package ${configured.package}`);
     let rendererCode;
     let plannerCode;
@@ -283,7 +284,7 @@ export function planProject(root, environment = "dev", options = {}) {
             const configuration = project.providers.configurations[flow.provider ?? project.defaults.provider ?? ""];
             check(configuration, "PROVIDER", "Select a provider for the ingestion flow");
             const selectedProvider = provider(project, profile.bindings, reader, flow.provider);
-            const providerSource = project.providers.packages[configuration.package]?.source;
+            const providerSource = projectPackages(project)[configuration.package]?.source;
             check(selectedProvider.plannerCode, "PROVIDER", "Ingestion requires a provider planner");
             const preset = flow.ingestion.preset
                 ? selectedProvider.packs[String(flow.ingestion.preset)]

package/dist/core/project-build.js

@@ -4,7 +4,7 @@ import { dirname, relative, resolve } from "node:path";
 import { validateProviderFiles } from "../plugins/generation.js";
 import { inspectProject, planProject } from "./planner.js";
 import { canonical, check, digest, isMap } from "./errors.js";
-import { canonicalPackageReference, fence, packageYaml, providerPackageSchema, resolvePackage, } from "./packages.js";
+import { configuredPackageReference, fence, packageYaml, providerPackageSchema, resolvePackage, } from "./packages.js";
 import { checkProviderCompatibility } from "../plugins/compatibility.js";
 import { prepareConnection } from "./connections.js";
 import { runProviderCommand } from "./provider-commands.js";
@@ -12,6 +12,7 @@ import { deliveryExports } from "./delivery-exports.js";
 import { renderProject, validateGeneratedFiles, writeOutput, } from "./generate.js";
 import { compilerFingerprint } from "./fingerprint.js";
 import { version } from "../version.js";
+import { projectPackages } from "./project-packages.js";
 export function buildProject(root, environment, args) {
     const { project, flows, reader, profile } = inspectProject(root, environment);
     check(!(args.provider && args.flow), "SELECT", "Choose provider or flow, not both");
@@ -116,9 +117,9 @@ export function buildProject(root, environment, args) {
         const selected = flows.filter((f) => wanted.has(f.id) && owner(f) === configuration);
         const config = project.providers.configurations[configuration];
         check(config, "PROVIDER", `Unknown provider configuration ${configuration}`);
-        const pkg = project.providers.packages[config.package];
+        const pkg = projectPackages(project)[config.package];
         check(pkg, "PACKAGE", `Missing execution package ${config.package}`);
-        const reference = canonicalPackageReference(`${pkg.source}@${pkg.version}`);
+        const reference = configuredPackageReference(pkg);
         const locked = pkg.source.startsWith(".")
             ? { file: reader.path(pkg.source), root, entry: undefined }
             : resolvePackage(root, reference);

package/dist/core/project-packages.d.ts

@@ -0,0 +1,7 @@
+import type { Project } from "./schema.js";
+export declare function projectPackages(project: Project): {
+    [x: string]: {
+        source: string;
+        version: string;
+    };
+};

package/dist/core/project-packages.js

@@ -0,0 +1,6 @@
+import { check } from "./errors.js";
+export function projectPackages(project) {
+    for (const name of Object.keys(project.packages))
+        check(!Object.hasOwn(project.providers.packages, name), "PACKAGE", `Package alias ${name} is declared twice`);
+    return { ...project.providers.packages, ...project.packages };
+}

package/dist/core/provider-commands.js

@@ -6,8 +6,9 @@ import { dirname, relative, resolve } from "node:path";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { Configuration } from "./config.js";
 import { projectSchema } from "./schema.js";
+import { projectPackages } from "./project-packages.js";
 import { canonical, check, digest } from "./errors.js";
-import { canonicalPackageReference, fence, packageYaml, providerPackageSchema, resolvePackage, } from "./packages.js";
+import { configuredPackageReference, fence, packageYaml, providerPackageSchema, resolvePackage, } from "./packages.js";
 import { executeProvider } from "../plugins/provider-renderer.js";
 import { checkProviderCompatibility } from "../plugins/compatibility.js";
 // No references, regular expressions or schema code: validation itself must be bounded.
@@ -65,9 +66,9 @@ function selected(root, environment, configuration) {
     check(project.environments[environment], "ENVIRONMENT", `Unknown environment ${environment}`);
     const configured = project.providers.configurations[configuration];
     check(configured, "PROVIDER", `Unknown provider configuration ${configuration}`);
-    const pkg = project.providers.packages[configured.package];
+    const pkg = projectPackages(project)[configured.package];
     check(pkg && !pkg.source.startsWith("builtin:") && !pkg.source.startsWith("."), "PACKAGE", "Provider commands require an installed locked provider");
-    const reference = canonicalPackageReference(`${pkg.source}@${pkg.version}`);
+    const reference = configuredPackageReference(pkg);
     const source = resolvePackage(reader.root, reference);
     const manifest = providerPackageSchema.parse(packageYaml(source.file));
     checkProviderCompatibility(manifest);
@@ -209,10 +210,10 @@ export function pluginCommands(root, environment) {
     const bindings = [];
     const owners = new Map();
     for (const [configuration, binding] of Object.entries(project.providers.configurations)) {
-        const pkg = project.providers.packages[binding.package];
+        const pkg = projectPackages(project)[binding.package];
         if (!pkg || pkg.source.startsWith("builtin:") || pkg.source.startsWith("."))
             continue;
-        const reference = canonicalPackageReference(`${pkg.source}@${pkg.version}`);
+        const reference = configuredPackageReference(pkg);
         const source = resolvePackage(reader.root, reference);
         const manifest = providerPackageSchema.parse(packageYaml(source.file));
         if (!manifest.commands)

package/dist/core/schema.d.ts

@@ -19,11 +19,15 @@ export declare const projectSchema: z.ZodObject<{
     apiVersion: z.ZodLiteral<"ingestron.project/v1">;
     id: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    packages: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodObject<{
+        source: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>, unknown>>>;
     providers: z.ZodObject<{
-        packages: z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodObject<{
+        packages: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodPreprocess<z.ZodObject<{
             source: z.ZodString;
             version: z.ZodString;
-        }, z.core.$strict>, unknown>>;
+        }, z.core.$strict>, unknown>>>;
         configurations: z.ZodRecord<z.ZodString, z.ZodObject<{
             package: z.ZodString;
             binding: z.ZodString;

package/dist/core/schema.js

@@ -30,9 +30,10 @@ export const projectSchema = z
     apiVersion: z.literal("ingestron.project/v1"),
     id,
     description: z.string().optional(),
+    packages: z.record(id, packageReferenceSchema).default({}),
     providers: z
         .object({
-        packages: z.record(id, packageReferenceSchema),
+        packages: z.record(id, packageReferenceSchema).default({}),
         configurations: z.record(id, providerSchema),
         packs: z.record(id, packageReferenceSchema).default({}),
     })

package/dist/core/workflows.js

@@ -148,6 +148,33 @@ function packageEditor(root) {
     };
     return { reader, project, finish };
 }
+function packageValue(raw, name) {
+    return raw.packages?.[name] ?? raw.providers?.packages?.[name];
+}
+function packagePath(raw, name) {
+    return raw.packages?.[name] ||
+        (raw.packages && !raw.providers?.packages?.[name])
+        ? ["packages", name]
+        : ["providers", "packages", name];
+}
+function sameInstalledPackage(root, left, right) {
+    try {
+        const a = resolvePackage(root, left).entry;
+        const b = resolvePackage(root, right).entry;
+        return (a.repository === b.repository &&
+            a.path === b.path &&
+            a.commit === b.commit);
+    }
+    catch {
+        return false;
+    }
+}
+function preferredReference(root, raw, full, id, version) {
+    const short = `${id}@${version}`;
+    return raw.packages && sameInstalledPackage(root, short, full)
+        ? short
+        : friendlyReference(full);
+}
 export function pluginConfigure(root, args) {
     const reference = canonicalPackageReference(args.reference);
     const sourceManifest = packageYaml(resolvePackage(root, reference).file);
@@ -156,41 +183,46 @@ export function pluginConfigure(root, args) {
         const { project, finish } = packageEditor(root);
         const name = identifier.parse(args.name ?? connector.id);
         const at = reference.lastIndexOf("@");
-        const friendly = friendlyReference(reference);
+        const raw = project.toJS();
+        const friendly = preferredReference(root, raw, reference, connector.id, connector.version);
         const value = {
             source: friendly.slice(0, friendly.lastIndexOf("@")),
             version: reference.slice(at + 1),
         };
-        const previous = project.getIn(["providers", "packages", name]);
+        const previous = packageValue(raw, 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");
+            const old = packageReferenceSchema.parse(previous);
+            check(sameInstalledPackage(root, `${old.source}@${old.version}`, reference) ||
+                (args.update &&
+                    (old.source === value.source ||
+                        old.source ===
+                            friendlyReference(reference).slice(0, -value.version.length - 1))), "CONFLICT", "Connector package key already exists; choose a different name");
         }
-        project.setIn(["providers", "packages", name], `${value.source}@${value.version}`);
+        project.setIn(packagePath(raw, 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 preferred = preferredReference(root, raw, canonicalPackageReference(args.reference), selected.manifest.id, selected.manifest.version);
     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]);
+        const existing = packageReferenceSchema.parse(packageValue(raw, 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`);
+            sameInstalledPackage(root, `${existing.source}@${existing.version}`, args.reference), "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}`);
+            check(existing.source === preferred.slice(0, preferred.lastIndexOf("@")) ||
+                friendlyReference(existing.source) === selected.source, "CONFLICT", "Use plugin migrate to change provider identity");
+            project.setIn(packagePath(raw, configurations[name].package), preferred);
             return finish({ "project.yaml": project.toString() });
         }
-        if (existing.source !== selected.source) {
-            project.setIn(["providers", "packages", configurations[name].package], `${selected.source}@${selected.version}`);
+        if (!sameInstalledPackage(root, `${existing.source}@${existing.version}`, args.reference)) {
+            project.setIn(packagePath(raw, configurations[name].package), preferred);
             return finish({ "project.yaml": project.toString() });
         }
         return finish({});
     }
-    check(!raw.providers.packages[name], "CONFLICT", `Package key ${name} already exists`);
+    check(!packageValue(raw, name), "CONFLICT", `Package key ${name} already exists`);
     const environmentNames = Object.keys(raw.environments);
     const files = providerAuthor(root, args.reference, {
         operation: "initialise",
@@ -204,7 +236,7 @@ export function pluginConfigure(root, args) {
     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}`);
+    project.setIn(packagePath(raw, name), preferred);
     const bindingName = `${name}_${defaults.binding}`;
     project.setIn(["providers", "configurations", name], {
         ...defaults,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingestron/core",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "type": "module",
   "description": "Shared Ingestron project compiler, operations and editor schemas",
   "license": "Apache-2.0",
@@ -34,8 +34,8 @@
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
     "quickjs-emscripten": "0.32.0",
-    "yaml": "2.9.0",
-    "zod": "4.5.4"
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
   },
   "publishConfig": {
     "access": "public",
@@ -45,16 +45,6 @@
     "type": "git",
     "url": "git+https://github.com/ingestron/core.git"
   },
-  "devDependencies": {
-    "@types/node": "22.20.1",
-    "prettier": "3.9.6",
-    "tsx": "4.23.13",
-    "typescript": "7.0.2"
-  },
-  "homepage": "https://ingestron.io",
-  "bugs": {
-    "url": "https://github.com/ingestron/core/issues"
-  },
   "scripts": {
     "build": "node scripts/build-assets.mjs && tsc && node scripts/compiler-fingerprint.mjs",
     "test": "tsx --test --test-concurrency=1 test/unit/*.test.ts test/providers/*.test.ts test/integration/*.test.ts",
@@ -64,6 +54,19 @@
     "release:check": "node scripts/release-check.mjs",
     "package:check": "tsx scripts/package-check.ts",
     "validate": "pnpm format:check && pnpm build && pnpm test && pnpm secrets:check && pnpm release:check && pnpm package:check",
+    "prepack": "npm run build",
+    "prepublishOnly": "node scripts/release-check.mjs --publish",
     "licences:inventory": "node scripts/licence-inventory.mjs"
+  },
+  "packageManager": "pnpm@10.15.0",
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "prettier": "3.9.8",
+    "tsx": "4.23.13",
+    "typescript": "7.0.2"
+  },
+  "homepage": "https://ingestron.io",
+  "bugs": {
+    "url": "https://github.com/ingestron/core/issues"
   }
-}
+}