@ingestron/core 0.12.2 → 0.12.4

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/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": "c144374cccbb512be7b3cd26700bc29538236eeeb35493eeec3bab938e08ff2a",
     "dist/core/config.js": "b7e7138f7cc4a7b4ec8f6d0f0616c8802f2d802ec29aa09b40c1fc5c9324e016",
-    "dist/core/connections.js": "504bbacd422fd0f6ef64a229f5255b377f5393a41f6366674fc5e8854a26b1d8",
-    "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",
@@ -23,14 +23,15 @@
     "dist/core/model-packs.js": "fee776ea0804dc66c9f140e57d94a3922d69c52d03c72079842ec43417616b0d",
     "dist/core/operations.js": "7f4a9eeee19d3e1e4c1beecc0350e38d386f012edfb31c3248efcd22ebd40a77",
     "dist/core/package-references.js": "bd3085eb6dcdac399d79af109d0a9e710a0532eba61e5298dc842aec9c7ef10a",
-    "dist/core/packages.js": "e30654122516573c1d8adf40f8a9e76acb54de090016751929dde679e4d1175b",
-    "dist/core/planner.js": "f91902f4c37a7588965360fcddbda79301b59a0b66ef2f70c0378fa5dfcc7088",
-    "dist/core/project-build.js": "1f1002b4f6c506986c5aa6a5bb01ad5f3b4658a7a1319b65d79eaa67916fb994",
-    "dist/core/provider-commands.js": "8bd82821f6ed0eefce8216e7c03c271f28cb9f4bfda7724d5c1de6be1855e535",
+    "dist/core/packages.js": "c6bcbc90aa3597fcd4205b27136221229d9efedc9bfa68a83a134cb5e8f51d2b",
+    "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": "4389a1c8994b1c5da6d470e29806e547d9e5c13ed481b5e34acbe919b6b4b3d8",
     "src/core/config.ts": "f282eb246438608e1951556dfeab9372daf65330a15a9d159d36d1f940370344",
-    "src/core/connections.ts": "84f5fb5522480b4c6cb9c90fcde65b5f8bf3db888352d0561b83dabad8ec2952",
-    "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",
@@ -62,14 +63,15 @@
     "src/core/model-packs.ts": "a110d319f6feeff22a2d0d3a99ce5e49e56817d0cc27ab77d831d04a945ddfd3",
     "src/core/operations.ts": "e0a5a0e869e96de4e869f89e0fd794cb9fa537a16fb1f37fd8cf2b7ca777c08d",
     "src/core/package-references.ts": "5c5cee7e140158928e2e5a37f426520c7c2f042546a37eed4507d79326181f5a",
-    "src/core/packages.ts": "afe307b5b8058a0dfd3bef76475b32f00be7d5a5b69e73b6c0fcc557aa528d8c",
-    "src/core/planner.ts": "498f5405f3088ee6d54ec8ab4a458813757697c150a56eab33f547aebb214da1",
-    "src/core/project-build.ts": "feb0fe50aff7b1fbdc8d96bcdb177a72a412639d1af98c3cff3b010de90a6428",
-    "src/core/provider-commands.ts": "f8a045230f61be0273910276b51e5c2e4bc0659f34c8a9361a38ab292c39eb4c",
+    "src/core/packages.ts": "8a9b6612325de68ab2610f540bd39e4f899b06d1cc1fbd54ecfd2abb8b4e9c40",
+    "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,8 +5,28 @@ 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 { packageReferenceSchema, projectSchema } from "./schema.js";
+import { projectPackages } from "./project-packages.js";
 import { contractColumns } from "./contracts.js";
-import { fence, installedProviders, canonicalPackageReference, } from "./packages.js";
+import { fence, installedProviders, canonicalPackageReference, configuredPackageReference, resolvePackage, packageYaml, } from "./packages.js";
+function concisePackageReference(root, value) {
+    const pkg = packageReferenceSchema.parse(value);
+    const reference = configuredPackageReference(pkg);
+    const installed = resolvePackage(root, reference);
+    const manifest = packageYaml(installed.file);
+    const short = `${manifest.id}@${manifest.version}`;
+    try {
+        const selected = resolvePackage(root, short);
+        if (selected.entry.repository === installed.entry.repository &&
+            selected.entry.path === installed.entry.path &&
+            selected.entry.commit === installed.entry.commit)
+            return short;
+    }
+    catch {
+        // Keep an explicit reference if multiple installed packages share the ID.
+    }
+    return `${pkg.source}@${pkg.version}`;
+}
 const yaml = (text, file) => {
     const doc = parseDocument(text, { uniqueKeys: true });
     check(!doc.errors.length, "YAML", doc.errors[0]?.message ?? "Invalid YAML", file);
@@ -114,7 +134,8 @@ export function initialise(root, options) {
             "project.yaml": stringify({
                 apiVersion: "ingestron.project/v1",
                 id: options.id,
-                providers: { packages: {}, configurations: {} },
+                packages: {},
+                providers: { configurations: {} },
                 defaults: {},
                 environments: Object.fromEntries(environments.map((name) => [
                     name,
@@ -148,6 +169,16 @@ export function initialise(root, options) {
         name === ".gitignore" ||
         /^environments\/[\w-]+\.yaml$/.test(name));
     check(files["project.yaml"], "PROVIDER", "Provider must author a project");
+    const authored = yaml(files["project.yaml"], "project.yaml").toJS();
+    const providerPackages = authored.providers?.packages ?? {};
+    authored.packages ??= {};
+    for (const [name, value] of Object.entries(providerPackages)) {
+        check(!Object.hasOwn(authored.packages, name), "PACKAGE", `Duplicate package alias ${name}`);
+        authored.packages[name] = concisePackageReference(root, value);
+    }
+    if (authored.providers)
+        delete authored.providers.packages;
+    files["project.yaml"] = stringify(authored);
     // Providers may return JSON (valid YAML); editable scaffolds use block YAML.
     for (const [name, text] of Object.entries(files)) {
         if (name.endsWith(".yaml"))
@@ -159,12 +190,14 @@ export function initialise(root, options) {
 }
 export function migrateProvider(root, options) {
     const reader = new Configuration(root), doc = yaml(reader.text("project.yaml"), "project.yaml");
-    check(doc.hasIn(["providers", "packages", options.package]), "PACKAGE", "Unknown project package");
+    const location = doc.hasIn(["packages", options.package])
+        ? ["packages", options.package]
+        : ["providers", "packages", options.package];
+    check(doc.hasIn(location), "PACKAGE", "Unknown project package");
     const selected = providerReference(root, options.to);
-    doc.setIn(["providers", "packages", options.package], {
-        source: selected.source,
-        version: selected.version,
-    });
+    doc.setIn(location, location[0] === "packages"
+        ? concisePackageReference(root, `${selected.source}@${selected.version}`)
+        : { source: selected.source, version: selected.version });
     return preview(root, { "project.yaml": doc.toString() });
 }
 function flowFile(root, id) {
@@ -186,7 +219,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);
@@ -196,7 +229,7 @@ export function addFlow(root, options) {
             value: yaml(reader.text(file), file).toJS(),
         };
     });
-    const files = providerAuthor(root, `${pkg.source}@${pkg.version}`, {
+    const files = providerAuthor(root, resolvePackage(root, configuredPackageReference(pkg)).reference, {
         operation: "flow",
         options,
         configuration,

package/dist/core/connections.js

@@ -7,8 +7,9 @@ import { resolveModelContracts } from "./model-packs.js";
 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) {
@@ -37,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");
@@ -88,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/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, {
@@ -190,6 +194,7 @@ export declare function packageLock(root: string): {
     }>;
 };
 export declare function resolvePackage(root: string, reference: string): {
+    reference: string;
     file: string;
     root: string;
     entry: {

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 &&
@@ -314,7 +332,7 @@ export function resolvePackage(root, reference) {
     check(canonical(inventory(cache)) === canonical(Object.keys(entry.files).sort()), "PACKAGE", "Package file inventory changed");
     for (const [file, hash] of Object.entries(entry.files))
         check(digest(readFileSync(fence(cache, file))) === hash, "PACKAGE", `Package integrity failed: ${file}`);
-    return { file: fence(cache, entry.path), root: cache, entry };
+    return { reference, file: fence(cache, entry.path), root: cache, entry };
 }
 /** Derived information lives outside the integrity-checked source cache. */
 export function savePluginInformation(root, reference) {

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/dist/plugins/authoring.d.ts

@@ -1,4 +1,5 @@
 export declare function providerReference(root: string, reference: string): {
+    reference: string;
     file: string;
     root: string;
     entry: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingestron/core",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "type": "module",
   "description": "Shared Ingestron project compiler, operations and editor schemas",
   "license": "Apache-2.0",