@postman-cs/onboarding-repo-sync 2.10.8 → 2.11.0

package/README.md

@@ -69,6 +69,15 @@ The example permissions let `GITHUB_TOKEN` commit generated artifacts and update
 
 `postman-access-token` is required: every asset operation (environment create/get/update, collection read, mock, monitor) plus workspace-to-repository linking and system environment association runs through the access-token gateway. Use `postman-resolve-service-token-action` to mint it at runtime from a [Postman service account](https://learning.postman.com/docs/administration/service-accounts/) PMAK. Without it the action fails fast — the PMAK is not an asset-routing fallback; it only mints/re-mints the access token, powers the generated CI workflow's `postman login --with-api-key`, and mints the CI `POSTMAN_API_KEY` secret. See [docs/credentials.md](docs/credentials.md).
 
+To manage the complete values for an environment, use a rich entry in the same input. String entries remain backward-compatible and receive generated values; rich entries replace the environment values exactly as supplied (plus the action's branch-ownership marker when applicable).
+
+```yaml
+environments-json: >-
+  [{"slug":"dev","values":[{"key":"baseUrl","value":"https://dev.example.com"},{"key":"jwtToken","value":"","type":"secret"}]}]
+```
+
+Secret-typed values must be empty. Supply the real secret as a masked runtime variable from the customer's vault when running the collection; repo-sync neither reads nor persists that value. `value`, `type`, and `enabled` default to `""`, `"default"`, and `true`. `env-runtime-urls-json` and generated credential slots apply only to string entries because a rich entry is the complete desired definition.
+
 ### Disable CI workflow generation
 
 For existing repositories that already own their CI workflow, disable workflow generation:
@@ -169,7 +178,7 @@ with:
 | `smoke-collection-id` | Smoke collection ID used for monitor creation. | no |  |
 | `contract-collection-id` | Contract collection ID used for exported artifacts. | no |  |
 | `onboarding-scope` | Onboarding scope. Use full for the complete pipeline or spec-only for repository linking and workspace/spec state only. | no | `full` |
-| `prebuilt-collections-json` | Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without cloud export. | no | `""` |
+| `prebuilt-collections-json` | Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without a cloud snapshot read. | no | `""` |
 | `collection-sync-mode` | Collection sync lifecycle mode (refresh or version). | no | `refresh` |
 | `spec-sync-mode` | Spec sync lifecycle mode (update or version). | no | `update` |
 | `release-label` | Optional release label used for versioned naming. | no |  |
@@ -178,7 +187,7 @@ with:
 | `mock-visibility` | Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync. | no | `private` |
 | `mock-environment-enabled` | Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential. | no | `false` |
 | `monitor-cron` | Cron expression for monitor scheduling (e.g. '0 */6 * * *'). When empty, the monitor is created disabled and triggered to run once per workflow invocation (and once on every subsequent run). | no | `""` |
-| `environments-json` | JSON array of environment slugs to create or update. | no | `["prod"]` |
+| `environments-json` | JSON array of environment slugs or full definitions ({slug, values}) to create or replace. Secret-typed values must be empty runtime slots. | no | `["prod"]` |
 | `git-provider` | Git provider override ('github', 'gitlab', 'bitbucket', 'azure-devops'). Auto-detected from environment when omitted. | no |  |
 | `ado-token` | Azure DevOps personal access token or system token used to push commits in Azure Pipelines. Defaults to SYSTEM_ACCESSTOKEN when available. | no |  |
 | `repo-url` | Explicit repository URL (GitHub, GitLab, or Azure DevOps). Defaults to the URL inferred from runner environment when omitted. For commit-and-push it must identify the checked-out origin. | no |  |

package/action.yml

@@ -43,7 +43,7 @@ inputs:
     required: false
     default: full
   prebuilt-collections-json:
-    description: Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without cloud export.
+    description: Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without a cloud snapshot read.
     required: false
     default: ''
   collection-sync-mode:
@@ -76,7 +76,7 @@ inputs:
     required: false
     default: ""
   environments-json:
-    description: JSON array of environment slugs to create or update.
+    description: JSON array of environment slugs or full definitions ({slug, values}) to create or replace. Secret-typed values must be empty runtime slots.
     required: false
     default: '["prod"]'
   git-provider:

package/dist/action.cjs

@@ -117719,6 +117719,7 @@ var path6 = __toESM(require("node:path"), 1);
 var V2 = __toESM(require_v2(), 1);
 var import_transforms = __toESM(require_transforms(), 1);
 var import_v3 = __toESM(require_node2(), 1);
+var V2_COLLECTION_MODEL = V2.Collection;
 function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
@@ -117739,13 +117740,23 @@ function normalizeGraphqlRequests(node) {
   }
 }
 async function convertAndSplitCollection(v2Collection, outputDir) {
-  const model = V2.Collection;
-  const parsed = model.parse(v2Collection ?? {});
-  const v3 = (0, import_transforms.transform)(model, import_transforms.FormatVersion.V3, parsed);
+  const v3 = convertV2CollectionToV3Collection(v2Collection);
+  await writeSplitCollection(v3, outputDir);
+}
+function convertV2CollectionToV3Collection(v2Collection) {
+  const parsed = V2_COLLECTION_MODEL.parse(v2Collection ?? {});
+  const v3 = (0, import_transforms.transform)(
+    V2_COLLECTION_MODEL,
+    import_transforms.FormatVersion.V3,
+    parsed
+  );
   for (const item of asArray(v3.items)) {
     normalizeGraphqlRequests(item);
   }
-  await writeSplitCollection(v3, outputDir);
+  return v3;
+}
+function assertV2CollectionModel(value) {
+  V2_COLLECTION_MODEL.parse(value ?? {});
 }
 function normalizeV3ExportIds(node) {
   if (!node || typeof node !== "object") return;
@@ -121303,7 +121314,7 @@ var postmanRepoSyncActionContract = {
       allowedValues: ["full", "spec-only"]
     },
     "prebuilt-collections-json": {
-      description: "Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without cloud export.",
+      description: "Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without a cloud snapshot read.",
       required: false,
       default: ""
     },
@@ -121346,7 +121357,7 @@ var postmanRepoSyncActionContract = {
       default: ""
     },
     "environments-json": {
-      description: "JSON array of environment slugs to create or update.",
+      description: "JSON array of environment slugs or full definitions ({slug, values}) to create or replace. Secret-typed values must be empty runtime slots.",
       required: false,
       default: '["prod"]'
     },
@@ -127837,8 +127848,8 @@ var PostmanGatewayAssetsClient = class {
   }
   /**
    * Validate and normalize a collection public UID for routes that require the
-   * full owner-prefixed UID (`<owner>-<uuid>`, 6 hyphen segments): collection
-   * GET export, collection-root PATCH/read, and private-mock runtime auth.
+   * full owner-prefixed UID (`<owner>-<uuid>`, 6 hyphen segments): populated
+   * collection snapshot, collection-root PATCH/read, and private-mock runtime auth.
    *
    * - Trims once.
    * - Rejects empty values.
@@ -128150,32 +128161,52 @@ var PostmanGatewayAssetsClient = class {
     );
     return match?.uid ? { uid: match.uid, name: match.name } : null;
   }
-  // --- collection read (service: collection, v3 export) ---
+  // --- collection read (service: sync, populated v2.1 snapshot) ---
   //
-  // The gateway `collection` service does NOT serve spec-generated uids on the
-  // v2 `/collections/:uid` path (404 RESOURCE_NOT_FOUND, live-probed). It DOES
-  // serve `GET /v3/collections/:id/export`, which returns the canonical v3
-  // collection IR (`{ data: { collection: { ... } } }`). That v3 IR is fed
-  // straight to `convertAndSplitV3Collection` — never round-tripped back to v2.
-  // The full owner-prefixed public UID must be sent verbatim; the bare model id
-  // is rejected on root mutation routes (403 FORBIDDEN) and must not be used
-  // here either, so the caller is responsible for passing the public UID.
+  // This is the canonical full collection read used by
+  // api-specification-service before whole-tree Sync updates. Collection v3
+  // `/export` performs an expensive projection and has returned 500s for fresh
+  // roots under provider load. The populated Sync read returns the complete
+  // v2.1 model directly and is transformed in memory through the official
+  // runtime.models V2 -> V3 pipeline before repository materialization.
   /**
-   * Fetch a collection's v3 IR through the gateway v3 export endpoint.
-   * Returns the `data.collection` object (canonical v3 shape with `$kind`
-   * discriminators, `items`, `variables`, `references`). Caller writes it to
-   * disk via `convertAndSplitV3Collection`. PMAK is never used for collection
-   * reads.
+   * Fetch one complete v2.1 collection through a single retry-free populated
+   * Sync GET. The response must be a v2.1 model for the requested public UID;
+   * malformed or foreign snapshots fail closed. PMAK is never used.
    */
   async getCollection(uid) {
     const id = this.requireCollectionPublicUid(uid);
     const response = await this.gateway.requestJson({
-      service: "collection",
+      service: "sync",
       method: "get",
-      path: `/v3/collections/${id}/export`
-    });
-    const data2 = this.asRecord(response?.data);
-    return data2?.collection ?? null;
+      path: `/collection/${encodeURIComponent(id)}`,
+      query: { populate: "true", format: "2.1.0", uid: "false" },
+      retry: "none",
+      fallback: "none"
+    });
+    const collection = this.asRecord(response?.data);
+    const info2 = this.asRecord(collection?.info);
+    const schema = typeof info2?.schema === "string" ? info2.schema.trim() : "";
+    if (!collection || !info2 || typeof info2.name !== "string" || !info2.name.trim() || !/\/collection\/v2\.1\.0\/collection\.json\/?$/i.test(schema) || !Array.isArray(collection.item)) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync read did not return a complete v2.1 collection"
+      );
+    }
+    try {
+      assertV2CollectionModel(collection);
+    } catch (error2) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync payload failed v2.1 schema validation",
+        { cause: error2 }
+      );
+    }
+    const observedId = String(info2._postman_id ?? collection.id ?? "").trim();
+    if (!observedId || this.toModelId(observedId).toLowerCase() !== this.toModelId(id).toLowerCase()) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync read returned a different collection identity"
+      );
+    }
+    return collection;
   }
   // --- mocks (service: mock) ---
   async createMock(workspaceId, name, collectionUid, environmentUid, requestedVisibility = "private") {
@@ -129567,13 +129598,117 @@ function parseJsonMap(raw) {
     ])
   );
 }
-function parseJsonArray(raw) {
-  if (!raw.trim()) return [];
-  const parsed = JSON.parse(raw);
+function parseEnvironmentInputs(raw) {
+  if (!raw.trim()) return { environments: [], definitions: /* @__PURE__ */ Object.create(null) };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("environments-json must contain valid JSON");
+  }
   if (!Array.isArray(parsed)) {
-    throw new Error("Expected JSON array");
+    throw new Error("environments-json must be a JSON array");
+  }
+  const environments = [];
+  const definitions = /* @__PURE__ */ Object.create(null);
+  const seen = /* @__PURE__ */ new Map();
+  parsed.forEach((entry, environmentIndex) => {
+    const label = `environments-json[${environmentIndex}]`;
+    let slug;
+    let rich = false;
+    if (typeof entry === "string") {
+      slug = entry;
+    } else {
+      if (!isPlainObject2(entry)) {
+        throw new Error(`${label} must be a slug string or an environment definition`);
+      }
+      const unknownFields = Object.keys(entry).filter((key) => key !== "slug" && key !== "values");
+      if (unknownFields.length > 0) {
+        throw new Error(`${label} contains unsupported field "${unknownFields[0]}"`);
+      }
+      if (typeof entry.slug !== "string" || !Array.isArray(entry.values)) {
+        throw new Error(`${label} must contain a string slug and a values array`);
+      }
+      slug = entry.slug;
+      rich = true;
+      const keys = /* @__PURE__ */ new Set();
+      definitions[slug] = entry.values.map((value, valueIndex) => {
+        const valueLabel = `${label}.values[${valueIndex}]`;
+        if (!isPlainObject2(value)) {
+          throw new Error(`${valueLabel} must be an object`);
+        }
+        const unknownValueFields = Object.keys(value).filter(
+          (key) => !["key", "value", "type", "enabled"].includes(key)
+        );
+        if (unknownValueFields.length > 0) {
+          throw new Error(`${valueLabel} contains unsupported field "${unknownValueFields[0]}"`);
+        }
+        if (typeof value.key !== "string" || !value.key.trim() || value.key !== value.key.trim()) {
+          throw new Error(`${valueLabel}.key must be a non-empty string without surrounding whitespace`);
+        }
+        if (value.key === "x-pm-onboarding") {
+          throw new Error(`${valueLabel}.key is reserved by repo-sync`);
+        }
+        if (keys.has(value.key)) {
+          throw new Error(`${label} contains duplicate variable key "${value.key}"`);
+        }
+        keys.add(value.key);
+        if (value.value !== void 0 && typeof value.value !== "string") {
+          throw new Error(`${valueLabel}.value must be a string when provided`);
+        }
+        if (value.type !== void 0 && value.type !== "default" && value.type !== "secret") {
+          throw new Error(`${valueLabel}.type must be "default" or "secret"`);
+        }
+        if (value.enabled !== void 0 && typeof value.enabled !== "boolean") {
+          throw new Error(`${valueLabel}.enabled must be a boolean when provided`);
+        }
+        const type = value.type ?? "default";
+        const normalizedValue = value.value ?? "";
+        if (type === "secret" && normalizedValue) {
+          throw new Error(`${valueLabel} cannot contain a populated secret value; inject it at runtime`);
+        }
+        return { key: value.key, value: normalizedValue, type, enabled: value.enabled ?? true };
+      });
+    }
+    if (rich && !/^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/.test(slug)) {
+      throw new Error(`${label} rich slug must use only letters, numbers, dots, hyphens, or underscores`);
+    }
+    if (rich && Object.prototype.hasOwnProperty.call(Object.prototype, slug)) {
+      throw new Error(`${label} rich slug conflicts with a reserved object property`);
+    }
+    if (rich && /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(slug)) {
+      throw new Error(`${label} rich slug conflicts with a Windows device name`);
+    }
+    if (!rich && !slug.trim()) {
+      throw new Error(`${label} slug must be a non-empty string`);
+    }
+    const priorWasRich = seen.get(slug);
+    if (priorWasRich !== void 0 && (rich || priorWasRich)) {
+      throw new Error(`environments-json contains duplicate slug "${slug}"`);
+    }
+    if (priorWasRich === void 0) seen.set(slug, rich);
+    environments.push(slug);
+  });
+  return { environments, definitions };
+}
+function normalizeProgrammaticEnvironmentDefinitions(inputs) {
+  const definitions = inputs.environmentDefinitions;
+  if (!definitions) return inputs;
+  const prototype = Object.getPrototypeOf(definitions);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new Error("environmentDefinitions must be a plain object");
+  }
+  const entries = inputs.environments.map(
+    (slug) => Object.prototype.hasOwnProperty.call(definitions, slug) ? { slug, values: definitions[slug] } : slug
+  );
+  let raw;
+  try {
+    raw = JSON.stringify(entries);
+  } catch {
+    throw new Error("environmentDefinitions must contain JSON-serializable values");
   }
-  return parsed.map((entry) => String(entry));
+  const parsed = parseEnvironmentInputs(raw);
+  return { ...inputs, environments: parsed.environments, environmentDefinitions: parsed.definitions };
 }
 function readInput(actionCore, name, required = false) {
   return actionCore.getInput(name, { required }).trim();
@@ -129670,7 +129805,7 @@ function resolveInputs(env = process.env) {
     },
     env
   );
-  const environments = parseJsonArray(getInput2("environments-json", env) || '["prod"]');
+  const parsedEnvironments = parseEnvironmentInputs(getInput2("environments-json", env) || '["prod"]');
   const secretsResolverProvider = parseSecretsResolverProvider(getInput2("secrets-resolver", env));
   const systemEnvMap = parseJsonMap(getInput2("system-env-map-json", env) || "{}");
   const environmentUids = parseJsonMap(getInput2("environment-uids-json", env) || "{}");
@@ -129708,7 +129843,8 @@ function resolveInputs(env = process.env) {
     secretsResolverProvider,
     specSyncMode: normalizeSpecSyncMode(getInput2("spec-sync-mode", env) || "update"),
     releaseLabel: normalizeReleaseLabel(getInput2("release-label", env)) || void 0,
-    environments: environments.length > 0 ? environments : ["prod"],
+    environments: parsedEnvironments.environments.length > 0 ? parsedEnvironments.environments : ["prod"],
+    environmentDefinitions: parsedEnvironments.definitions,
     repoUrl: repoContext.repoUrl || "",
     integrationBackend: getInput2("integration-backend", env) || "bifrost",
     workspaceLinkEnabled: parseBooleanInput(getInput2("workspace-link-enabled", env), true),
@@ -130376,7 +130512,8 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
         }
       } catch {
       }
-      const values2 = buildEnvironmentValues(envName, runtimeUrl, {
+      const definedValues2 = inputs.environmentDefinitions?.[envName];
+      const values2 = definedValues2 ? definedValues2.map((value) => ({ ...value })) : buildEnvironmentValues(envName, runtimeUrl, {
         secretsResolverProvider: inputs.secretsResolverProvider,
         preservedCredentialValues: priorValues
       });
@@ -130399,7 +130536,8 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
       dependencies.core.setOutput("environment-uids-json", JSON.stringify(envUids));
       continue;
     }
-    const values = buildEnvironmentValues(envName, runtimeUrl, {
+    const definedValues = inputs.environmentDefinitions?.[envName];
+    const values = definedValues ? definedValues.map((value) => ({ ...value })) : buildEnvironmentValues(envName, runtimeUrl, {
       secretsResolverProvider: inputs.secretsResolverProvider
     });
     if (assetMarker) values.push({ key: "x-pm-onboarding", value: JSON.stringify(assetMarker), type: "default" });
@@ -131183,13 +131321,14 @@ function applyPrivateMockPrebuiltPlans(plans) {
   }
 }
 async function preparePrivateMockCloudCollection(role, collectionId, postman) {
-  const col = await postman.getCollection(collectionId);
-  const { collection } = applyPrivateMockExportCleanup(col, {
+  const snapshot = await postman.getCollection(collectionId);
+  const v3Collection = convertV2CollectionToV3Collection(snapshot);
+  const { collection } = applyPrivateMockExportCleanup(v3Collection, {
     stripManagedBlocks: isPrivateMockLegacyExportCleanupEnabled()
   });
   if (!verifyPrivateMockRootHook(collection)) {
     throw new Error(
-      `PRIVATE_MOCK_AUTH_ROOT_UNVERIFIED: Managed root hook missing from exported ${role} collection ${collectionId}`
+      `PRIVATE_MOCK_AUTH_ROOT_UNVERIFIED: Managed root hook missing from populated ${role} collection snapshot ${collectionId}`
     );
   }
   return collection;
@@ -131235,7 +131374,7 @@ async function acquireCollectionArtifact(options) {
     return { reusePrebuilt: true };
   }
   if (entry) {
-    core.info(privateMockAuth ? `Private mock has no locally reconciled exact prebuilt ${role} collection; exporting from cloud` : `Prebuilt ${role} collection entry present but did not exactly match; exporting from cloud`);
+    core.info(privateMockAuth ? `Private mock has no locally reconciled exact prebuilt ${role} collection; reading populated cloud snapshot` : `Prebuilt ${role} collection entry present but did not exactly match; reading populated cloud snapshot`);
   }
   const cloud = privateMockAuth ? await preparePrivateMockCloudCollection(role, collectionId, postman) : await postman.getCollection(collectionId);
   return { reusePrebuilt: false, cloudCollection: cloud };
@@ -131589,6 +131728,7 @@ async function commitAndPushGeneratedFiles(inputs, dependencies, privateMockAuth
   };
 }
 async function runRepoSync(inputs, dependencies, executionContext) {
+  inputs = normalizeProgrammaticEnvironmentDefinitions(inputs);
   const telemetry = createTelemetryContext({ action: "postman-repo-sync-action", actionVersion: resolveActionVersion2(), logger: dependencies.core });
   telemetry.setTeamId(dependencies.teamId);
   const logger = resolveRepoSyncLogger(dependencies);
@@ -132482,9 +132622,9 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     getEnvironment: gatewayAssets.getEnvironment.bind(gatewayAssets),
     updateEnvironment: gatewayAssets.updateEnvironment.bind(gatewayAssets),
     findEnvironmentByName: gatewayAssets.findEnvironmentByName.bind(gatewayAssets),
-    // Collection read via the v3 export endpoint — returns canonical v3 IR,
-    // written to disk by `convertAndSplitAnyCollection`. PMAK is never used for
-    // collection reads.
+    // Collection read via one retry-free populated Sync GET — returns a full
+    // v2.1 snapshot that the official runtime.models transform converts to v3
+    // before repository materialization. PMAK is never used for reads.
     getCollection: gatewayAssets.getCollection.bind(gatewayAssets),
     // Mocks via the `mock` service, collection-based monitors via the `monitors`
     // service (jobTemplates). Both reference the collection by its full public

package/dist/cli.cjs

@@ -115824,6 +115824,7 @@ var path = __toESM(require("node:path"), 1);
 var V2 = __toESM(require_v2(), 1);
 var import_transforms = __toESM(require_transforms(), 1);
 var import_v3 = __toESM(require_node2(), 1);
+var V2_COLLECTION_MODEL = V2.Collection;
 function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
@@ -115844,13 +115845,23 @@ function normalizeGraphqlRequests(node) {
   }
 }
 async function convertAndSplitCollection(v2Collection, outputDir) {
-  const model = V2.Collection;
-  const parsed = model.parse(v2Collection ?? {});
-  const v3 = (0, import_transforms.transform)(model, import_transforms.FormatVersion.V3, parsed);
+  const v3 = convertV2CollectionToV3Collection(v2Collection);
+  await writeSplitCollection(v3, outputDir);
+}
+function convertV2CollectionToV3Collection(v2Collection) {
+  const parsed = V2_COLLECTION_MODEL.parse(v2Collection ?? {});
+  const v3 = (0, import_transforms.transform)(
+    V2_COLLECTION_MODEL,
+    import_transforms.FormatVersion.V3,
+    parsed
+  );
   for (const item of asArray(v3.items)) {
     normalizeGraphqlRequests(item);
   }
-  await writeSplitCollection(v3, outputDir);
+  return v3;
+}
+function assertV2CollectionModel(value) {
+  V2_COLLECTION_MODEL.parse(value ?? {});
 }
 function normalizeV3ExportIds(node) {
   if (!node || typeof node !== "object") return;
@@ -119408,7 +119419,7 @@ var postmanRepoSyncActionContract = {
       allowedValues: ["full", "spec-only"]
     },
     "prebuilt-collections-json": {
-      description: "Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without cloud export.",
+      description: "Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without a cloud snapshot read.",
       required: false,
       default: ""
     },
@@ -119451,7 +119462,7 @@ var postmanRepoSyncActionContract = {
       default: ""
     },
     "environments-json": {
-      description: "JSON array of environment slugs to create or update.",
+      description: "JSON array of environment slugs or full definitions ({slug, values}) to create or replace. Secret-typed values must be empty runtime slots.",
       required: false,
       default: '["prod"]'
     },
@@ -125942,8 +125953,8 @@ var PostmanGatewayAssetsClient = class {
   }
   /**
    * Validate and normalize a collection public UID for routes that require the
-   * full owner-prefixed UID (`<owner>-<uuid>`, 6 hyphen segments): collection
-   * GET export, collection-root PATCH/read, and private-mock runtime auth.
+   * full owner-prefixed UID (`<owner>-<uuid>`, 6 hyphen segments): populated
+   * collection snapshot, collection-root PATCH/read, and private-mock runtime auth.
    *
    * - Trims once.
    * - Rejects empty values.
@@ -126255,32 +126266,52 @@ var PostmanGatewayAssetsClient = class {
     );
     return match?.uid ? { uid: match.uid, name: match.name } : null;
   }
-  // --- collection read (service: collection, v3 export) ---
+  // --- collection read (service: sync, populated v2.1 snapshot) ---
   //
-  // The gateway `collection` service does NOT serve spec-generated uids on the
-  // v2 `/collections/:uid` path (404 RESOURCE_NOT_FOUND, live-probed). It DOES
-  // serve `GET /v3/collections/:id/export`, which returns the canonical v3
-  // collection IR (`{ data: { collection: { ... } } }`). That v3 IR is fed
-  // straight to `convertAndSplitV3Collection` — never round-tripped back to v2.
-  // The full owner-prefixed public UID must be sent verbatim; the bare model id
-  // is rejected on root mutation routes (403 FORBIDDEN) and must not be used
-  // here either, so the caller is responsible for passing the public UID.
+  // This is the canonical full collection read used by
+  // api-specification-service before whole-tree Sync updates. Collection v3
+  // `/export` performs an expensive projection and has returned 500s for fresh
+  // roots under provider load. The populated Sync read returns the complete
+  // v2.1 model directly and is transformed in memory through the official
+  // runtime.models V2 -> V3 pipeline before repository materialization.
   /**
-   * Fetch a collection's v3 IR through the gateway v3 export endpoint.
-   * Returns the `data.collection` object (canonical v3 shape with `$kind`
-   * discriminators, `items`, `variables`, `references`). Caller writes it to
-   * disk via `convertAndSplitV3Collection`. PMAK is never used for collection
-   * reads.
+   * Fetch one complete v2.1 collection through a single retry-free populated
+   * Sync GET. The response must be a v2.1 model for the requested public UID;
+   * malformed or foreign snapshots fail closed. PMAK is never used.
    */
   async getCollection(uid) {
     const id = this.requireCollectionPublicUid(uid);
     const response = await this.gateway.requestJson({
-      service: "collection",
+      service: "sync",
       method: "get",
-      path: `/v3/collections/${id}/export`
-    });
-    const data2 = this.asRecord(response?.data);
-    return data2?.collection ?? null;
+      path: `/collection/${encodeURIComponent(id)}`,
+      query: { populate: "true", format: "2.1.0", uid: "false" },
+      retry: "none",
+      fallback: "none"
+    });
+    const collection = this.asRecord(response?.data);
+    const info = this.asRecord(collection?.info);
+    const schema = typeof info?.schema === "string" ? info.schema.trim() : "";
+    if (!collection || !info || typeof info.name !== "string" || !info.name.trim() || !/\/collection\/v2\.1\.0\/collection\.json\/?$/i.test(schema) || !Array.isArray(collection.item)) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync read did not return a complete v2.1 collection"
+      );
+    }
+    try {
+      assertV2CollectionModel(collection);
+    } catch (error) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync payload failed v2.1 schema validation",
+        { cause: error }
+      );
+    }
+    const observedId = String(info._postman_id ?? collection.id ?? "").trim();
+    if (!observedId || this.toModelId(observedId).toLowerCase() !== this.toModelId(id).toLowerCase()) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync read returned a different collection identity"
+      );
+    }
+    return collection;
   }
   // --- mocks (service: mock) ---
   async createMock(workspaceId, name, collectionUid, environmentUid, requestedVisibility = "private") {
@@ -127620,13 +127651,117 @@ function parseJsonMap(raw) {
     ])
   );
 }
-function parseJsonArray(raw) {
-  if (!raw.trim()) return [];
-  const parsed = JSON.parse(raw);
+function parseEnvironmentInputs(raw) {
+  if (!raw.trim()) return { environments: [], definitions: /* @__PURE__ */ Object.create(null) };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("environments-json must contain valid JSON");
+  }
   if (!Array.isArray(parsed)) {
-    throw new Error("Expected JSON array");
+    throw new Error("environments-json must be a JSON array");
+  }
+  const environments = [];
+  const definitions = /* @__PURE__ */ Object.create(null);
+  const seen = /* @__PURE__ */ new Map();
+  parsed.forEach((entry, environmentIndex) => {
+    const label = `environments-json[${environmentIndex}]`;
+    let slug;
+    let rich = false;
+    if (typeof entry === "string") {
+      slug = entry;
+    } else {
+      if (!isPlainObject2(entry)) {
+        throw new Error(`${label} must be a slug string or an environment definition`);
+      }
+      const unknownFields = Object.keys(entry).filter((key) => key !== "slug" && key !== "values");
+      if (unknownFields.length > 0) {
+        throw new Error(`${label} contains unsupported field "${unknownFields[0]}"`);
+      }
+      if (typeof entry.slug !== "string" || !Array.isArray(entry.values)) {
+        throw new Error(`${label} must contain a string slug and a values array`);
+      }
+      slug = entry.slug;
+      rich = true;
+      const keys = /* @__PURE__ */ new Set();
+      definitions[slug] = entry.values.map((value, valueIndex) => {
+        const valueLabel = `${label}.values[${valueIndex}]`;
+        if (!isPlainObject2(value)) {
+          throw new Error(`${valueLabel} must be an object`);
+        }
+        const unknownValueFields = Object.keys(value).filter(
+          (key) => !["key", "value", "type", "enabled"].includes(key)
+        );
+        if (unknownValueFields.length > 0) {
+          throw new Error(`${valueLabel} contains unsupported field "${unknownValueFields[0]}"`);
+        }
+        if (typeof value.key !== "string" || !value.key.trim() || value.key !== value.key.trim()) {
+          throw new Error(`${valueLabel}.key must be a non-empty string without surrounding whitespace`);
+        }
+        if (value.key === "x-pm-onboarding") {
+          throw new Error(`${valueLabel}.key is reserved by repo-sync`);
+        }
+        if (keys.has(value.key)) {
+          throw new Error(`${label} contains duplicate variable key "${value.key}"`);
+        }
+        keys.add(value.key);
+        if (value.value !== void 0 && typeof value.value !== "string") {
+          throw new Error(`${valueLabel}.value must be a string when provided`);
+        }
+        if (value.type !== void 0 && value.type !== "default" && value.type !== "secret") {
+          throw new Error(`${valueLabel}.type must be "default" or "secret"`);
+        }
+        if (value.enabled !== void 0 && typeof value.enabled !== "boolean") {
+          throw new Error(`${valueLabel}.enabled must be a boolean when provided`);
+        }
+        const type = value.type ?? "default";
+        const normalizedValue = value.value ?? "";
+        if (type === "secret" && normalizedValue) {
+          throw new Error(`${valueLabel} cannot contain a populated secret value; inject it at runtime`);
+        }
+        return { key: value.key, value: normalizedValue, type, enabled: value.enabled ?? true };
+      });
+    }
+    if (rich && !/^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/.test(slug)) {
+      throw new Error(`${label} rich slug must use only letters, numbers, dots, hyphens, or underscores`);
+    }
+    if (rich && Object.prototype.hasOwnProperty.call(Object.prototype, slug)) {
+      throw new Error(`${label} rich slug conflicts with a reserved object property`);
+    }
+    if (rich && /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(slug)) {
+      throw new Error(`${label} rich slug conflicts with a Windows device name`);
+    }
+    if (!rich && !slug.trim()) {
+      throw new Error(`${label} slug must be a non-empty string`);
+    }
+    const priorWasRich = seen.get(slug);
+    if (priorWasRich !== void 0 && (rich || priorWasRich)) {
+      throw new Error(`environments-json contains duplicate slug "${slug}"`);
+    }
+    if (priorWasRich === void 0) seen.set(slug, rich);
+    environments.push(slug);
+  });
+  return { environments, definitions };
+}
+function normalizeProgrammaticEnvironmentDefinitions(inputs) {
+  const definitions = inputs.environmentDefinitions;
+  if (!definitions) return inputs;
+  const prototype = Object.getPrototypeOf(definitions);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new Error("environmentDefinitions must be a plain object");
+  }
+  const entries = inputs.environments.map(
+    (slug) => Object.prototype.hasOwnProperty.call(definitions, slug) ? { slug, values: definitions[slug] } : slug
+  );
+  let raw;
+  try {
+    raw = JSON.stringify(entries);
+  } catch {
+    throw new Error("environmentDefinitions must contain JSON-serializable values");
   }
-  return parsed.map((entry) => String(entry));
+  const parsed = parseEnvironmentInputs(raw);
+  return { ...inputs, environments: parsed.environments, environmentDefinitions: parsed.definitions };
 }
 function normalizeRepoWriteMode(value) {
   if (value === "none" || value === "commit-only" || value === "commit-and-push") {
@@ -127720,7 +127855,7 @@ function resolveInputs(env = process.env) {
     },
     env
   );
-  const environments = parseJsonArray(getInput("environments-json", env) || '["prod"]');
+  const parsedEnvironments = parseEnvironmentInputs(getInput("environments-json", env) || '["prod"]');
   const secretsResolverProvider = parseSecretsResolverProvider(getInput("secrets-resolver", env));
   const systemEnvMap = parseJsonMap(getInput("system-env-map-json", env) || "{}");
   const environmentUids = parseJsonMap(getInput("environment-uids-json", env) || "{}");
@@ -127758,7 +127893,8 @@ function resolveInputs(env = process.env) {
     secretsResolverProvider,
     specSyncMode: normalizeSpecSyncMode(getInput("spec-sync-mode", env) || "update"),
     releaseLabel: normalizeReleaseLabel(getInput("release-label", env)) || void 0,
-    environments: environments.length > 0 ? environments : ["prod"],
+    environments: parsedEnvironments.environments.length > 0 ? parsedEnvironments.environments : ["prod"],
+    environmentDefinitions: parsedEnvironments.definitions,
     repoUrl: repoContext.repoUrl || "",
     integrationBackend: getInput("integration-backend", env) || "bifrost",
     workspaceLinkEnabled: parseBooleanInput(getInput("workspace-link-enabled", env), true),
@@ -128285,7 +128421,8 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
         }
       } catch {
       }
-      const values2 = buildEnvironmentValues(envName, runtimeUrl, {
+      const definedValues2 = inputs.environmentDefinitions?.[envName];
+      const values2 = definedValues2 ? definedValues2.map((value) => ({ ...value })) : buildEnvironmentValues(envName, runtimeUrl, {
         secretsResolverProvider: inputs.secretsResolverProvider,
         preservedCredentialValues: priorValues
       });
@@ -128308,7 +128445,8 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
       dependencies.core.setOutput("environment-uids-json", JSON.stringify(envUids));
       continue;
     }
-    const values = buildEnvironmentValues(envName, runtimeUrl, {
+    const definedValues = inputs.environmentDefinitions?.[envName];
+    const values = definedValues ? definedValues.map((value) => ({ ...value })) : buildEnvironmentValues(envName, runtimeUrl, {
       secretsResolverProvider: inputs.secretsResolverProvider
     });
     if (assetMarker) values.push({ key: "x-pm-onboarding", value: JSON.stringify(assetMarker), type: "default" });
@@ -129092,13 +129230,14 @@ function applyPrivateMockPrebuiltPlans(plans) {
   }
 }
 async function preparePrivateMockCloudCollection(role, collectionId, postman) {
-  const col = await postman.getCollection(collectionId);
-  const { collection } = applyPrivateMockExportCleanup(col, {
+  const snapshot = await postman.getCollection(collectionId);
+  const v3Collection = convertV2CollectionToV3Collection(snapshot);
+  const { collection } = applyPrivateMockExportCleanup(v3Collection, {
     stripManagedBlocks: isPrivateMockLegacyExportCleanupEnabled()
   });
   if (!verifyPrivateMockRootHook(collection)) {
     throw new Error(
-      `PRIVATE_MOCK_AUTH_ROOT_UNVERIFIED: Managed root hook missing from exported ${role} collection ${collectionId}`
+      `PRIVATE_MOCK_AUTH_ROOT_UNVERIFIED: Managed root hook missing from populated ${role} collection snapshot ${collectionId}`
     );
   }
   return collection;
@@ -129144,7 +129283,7 @@ async function acquireCollectionArtifact(options) {
     return { reusePrebuilt: true };
   }
   if (entry) {
-    core.info(privateMockAuth ? `Private mock has no locally reconciled exact prebuilt ${role} collection; exporting from cloud` : `Prebuilt ${role} collection entry present but did not exactly match; exporting from cloud`);
+    core.info(privateMockAuth ? `Private mock has no locally reconciled exact prebuilt ${role} collection; reading populated cloud snapshot` : `Prebuilt ${role} collection entry present but did not exactly match; reading populated cloud snapshot`);
   }
   const cloud = privateMockAuth ? await preparePrivateMockCloudCollection(role, collectionId, postman) : await postman.getCollection(collectionId);
   return { reusePrebuilt: false, cloudCollection: cloud };
@@ -129498,6 +129637,7 @@ async function commitAndPushGeneratedFiles(inputs, dependencies, privateMockAuth
   };
 }
 async function runRepoSync(inputs, dependencies, executionContext) {
+  inputs = normalizeProgrammaticEnvironmentDefinitions(inputs);
   const telemetry = createTelemetryContext({ action: "postman-repo-sync-action", actionVersion: resolveActionVersion2(), logger: dependencies.core });
   telemetry.setTeamId(dependencies.teamId);
   const logger = resolveRepoSyncLogger(dependencies);
@@ -130391,9 +130531,9 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     getEnvironment: gatewayAssets.getEnvironment.bind(gatewayAssets),
     updateEnvironment: gatewayAssets.updateEnvironment.bind(gatewayAssets),
     findEnvironmentByName: gatewayAssets.findEnvironmentByName.bind(gatewayAssets),
-    // Collection read via the v3 export endpoint — returns canonical v3 IR,
-    // written to disk by `convertAndSplitAnyCollection`. PMAK is never used for
-    // collection reads.
+    // Collection read via one retry-free populated Sync GET — returns a full
+    // v2.1 snapshot that the official runtime.models transform converts to v3
+    // before repository materialization. PMAK is never used for reads.
     getCollection: gatewayAssets.getCollection.bind(gatewayAssets),
     // Mocks via the `mock` service, collection-based monitors via the `monitors`
     // service (jobTemplates). Both reference the collection by its full public

package/dist/index.cjs

@@ -117745,6 +117745,7 @@ var path6 = __toESM(require("node:path"), 1);
 var V2 = __toESM(require_v2(), 1);
 var import_transforms = __toESM(require_transforms(), 1);
 var import_v3 = __toESM(require_node2(), 1);
+var V2_COLLECTION_MODEL = V2.Collection;
 function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
@@ -117765,13 +117766,23 @@ function normalizeGraphqlRequests(node) {
   }
 }
 async function convertAndSplitCollection(v2Collection, outputDir) {
-  const model = V2.Collection;
-  const parsed = model.parse(v2Collection ?? {});
-  const v3 = (0, import_transforms.transform)(model, import_transforms.FormatVersion.V3, parsed);
+  const v3 = convertV2CollectionToV3Collection(v2Collection);
+  await writeSplitCollection(v3, outputDir);
+}
+function convertV2CollectionToV3Collection(v2Collection) {
+  const parsed = V2_COLLECTION_MODEL.parse(v2Collection ?? {});
+  const v3 = (0, import_transforms.transform)(
+    V2_COLLECTION_MODEL,
+    import_transforms.FormatVersion.V3,
+    parsed
+  );
   for (const item of asArray(v3.items)) {
     normalizeGraphqlRequests(item);
   }
-  await writeSplitCollection(v3, outputDir);
+  return v3;
+}
+function assertV2CollectionModel(value) {
+  V2_COLLECTION_MODEL.parse(value ?? {});
 }
 function normalizeV3ExportIds(node) {
   if (!node || typeof node !== "object") return;
@@ -121329,7 +121340,7 @@ var postmanRepoSyncActionContract = {
       allowedValues: ["full", "spec-only"]
     },
     "prebuilt-collections-json": {
-      description: "Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without cloud export.",
+      description: "Optional digest-bound JSON manifest of unique baseline, smoke, or contract roles with confined repo-relative path, SHA-256 artifact digest of the on-disk v3 collection tree (sorted relative-path + NUL + bytes + NUL), and canonical cloud ID. The optional payloadDigest field is the semantic v2 payload digest carried for provenance (format-validated only, not the reuse gate). Exact role, path, cloudId, and artifactDigest matches reuse the on-disk tree without a cloud snapshot read.",
       required: false,
       default: ""
     },
@@ -121372,7 +121383,7 @@ var postmanRepoSyncActionContract = {
       default: ""
     },
     "environments-json": {
-      description: "JSON array of environment slugs to create or update.",
+      description: "JSON array of environment slugs or full definitions ({slug, values}) to create or replace. Secret-typed values must be empty runtime slots.",
       required: false,
       default: '["prod"]'
     },
@@ -127863,8 +127874,8 @@ var PostmanGatewayAssetsClient = class {
   }
   /**
    * Validate and normalize a collection public UID for routes that require the
-   * full owner-prefixed UID (`<owner>-<uuid>`, 6 hyphen segments): collection
-   * GET export, collection-root PATCH/read, and private-mock runtime auth.
+   * full owner-prefixed UID (`<owner>-<uuid>`, 6 hyphen segments): populated
+   * collection snapshot, collection-root PATCH/read, and private-mock runtime auth.
    *
    * - Trims once.
    * - Rejects empty values.
@@ -128176,32 +128187,52 @@ var PostmanGatewayAssetsClient = class {
     );
     return match?.uid ? { uid: match.uid, name: match.name } : null;
   }
-  // --- collection read (service: collection, v3 export) ---
+  // --- collection read (service: sync, populated v2.1 snapshot) ---
   //
-  // The gateway `collection` service does NOT serve spec-generated uids on the
-  // v2 `/collections/:uid` path (404 RESOURCE_NOT_FOUND, live-probed). It DOES
-  // serve `GET /v3/collections/:id/export`, which returns the canonical v3
-  // collection IR (`{ data: { collection: { ... } } }`). That v3 IR is fed
-  // straight to `convertAndSplitV3Collection` — never round-tripped back to v2.
-  // The full owner-prefixed public UID must be sent verbatim; the bare model id
-  // is rejected on root mutation routes (403 FORBIDDEN) and must not be used
-  // here either, so the caller is responsible for passing the public UID.
+  // This is the canonical full collection read used by
+  // api-specification-service before whole-tree Sync updates. Collection v3
+  // `/export` performs an expensive projection and has returned 500s for fresh
+  // roots under provider load. The populated Sync read returns the complete
+  // v2.1 model directly and is transformed in memory through the official
+  // runtime.models V2 -> V3 pipeline before repository materialization.
   /**
-   * Fetch a collection's v3 IR through the gateway v3 export endpoint.
-   * Returns the `data.collection` object (canonical v3 shape with `$kind`
-   * discriminators, `items`, `variables`, `references`). Caller writes it to
-   * disk via `convertAndSplitV3Collection`. PMAK is never used for collection
-   * reads.
+   * Fetch one complete v2.1 collection through a single retry-free populated
+   * Sync GET. The response must be a v2.1 model for the requested public UID;
+   * malformed or foreign snapshots fail closed. PMAK is never used.
    */
   async getCollection(uid) {
     const id = this.requireCollectionPublicUid(uid);
     const response = await this.gateway.requestJson({
-      service: "collection",
+      service: "sync",
       method: "get",
-      path: `/v3/collections/${id}/export`
-    });
-    const data2 = this.asRecord(response?.data);
-    return data2?.collection ?? null;
+      path: `/collection/${encodeURIComponent(id)}`,
+      query: { populate: "true", format: "2.1.0", uid: "false" },
+      retry: "none",
+      fallback: "none"
+    });
+    const collection = this.asRecord(response?.data);
+    const info2 = this.asRecord(collection?.info);
+    const schema = typeof info2?.schema === "string" ? info2.schema.trim() : "";
+    if (!collection || !info2 || typeof info2.name !== "string" || !info2.name.trim() || !/\/collection\/v2\.1\.0\/collection\.json\/?$/i.test(schema) || !Array.isArray(collection.item)) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync read did not return a complete v2.1 collection"
+      );
+    }
+    try {
+      assertV2CollectionModel(collection);
+    } catch (error2) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync payload failed v2.1 schema validation",
+        { cause: error2 }
+      );
+    }
+    const observedId = String(info2._postman_id ?? collection.id ?? "").trim();
+    if (!observedId || this.toModelId(observedId).toLowerCase() !== this.toModelId(id).toLowerCase()) {
+      throw new Error(
+        "COLLECTION_SNAPSHOT_INVALID: populated Sync read returned a different collection identity"
+      );
+    }
+    return collection;
   }
   // --- mocks (service: mock) ---
   async createMock(workspaceId, name, collectionUid, environmentUid, requestedVisibility = "private") {
@@ -129593,13 +129624,117 @@ function parseJsonMap(raw) {
     ])
   );
 }
-function parseJsonArray(raw) {
-  if (!raw.trim()) return [];
-  const parsed = JSON.parse(raw);
+function parseEnvironmentInputs(raw) {
+  if (!raw.trim()) return { environments: [], definitions: /* @__PURE__ */ Object.create(null) };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("environments-json must contain valid JSON");
+  }
   if (!Array.isArray(parsed)) {
-    throw new Error("Expected JSON array");
+    throw new Error("environments-json must be a JSON array");
+  }
+  const environments = [];
+  const definitions = /* @__PURE__ */ Object.create(null);
+  const seen = /* @__PURE__ */ new Map();
+  parsed.forEach((entry, environmentIndex) => {
+    const label = `environments-json[${environmentIndex}]`;
+    let slug;
+    let rich = false;
+    if (typeof entry === "string") {
+      slug = entry;
+    } else {
+      if (!isPlainObject2(entry)) {
+        throw new Error(`${label} must be a slug string or an environment definition`);
+      }
+      const unknownFields = Object.keys(entry).filter((key) => key !== "slug" && key !== "values");
+      if (unknownFields.length > 0) {
+        throw new Error(`${label} contains unsupported field "${unknownFields[0]}"`);
+      }
+      if (typeof entry.slug !== "string" || !Array.isArray(entry.values)) {
+        throw new Error(`${label} must contain a string slug and a values array`);
+      }
+      slug = entry.slug;
+      rich = true;
+      const keys = /* @__PURE__ */ new Set();
+      definitions[slug] = entry.values.map((value, valueIndex) => {
+        const valueLabel = `${label}.values[${valueIndex}]`;
+        if (!isPlainObject2(value)) {
+          throw new Error(`${valueLabel} must be an object`);
+        }
+        const unknownValueFields = Object.keys(value).filter(
+          (key) => !["key", "value", "type", "enabled"].includes(key)
+        );
+        if (unknownValueFields.length > 0) {
+          throw new Error(`${valueLabel} contains unsupported field "${unknownValueFields[0]}"`);
+        }
+        if (typeof value.key !== "string" || !value.key.trim() || value.key !== value.key.trim()) {
+          throw new Error(`${valueLabel}.key must be a non-empty string without surrounding whitespace`);
+        }
+        if (value.key === "x-pm-onboarding") {
+          throw new Error(`${valueLabel}.key is reserved by repo-sync`);
+        }
+        if (keys.has(value.key)) {
+          throw new Error(`${label} contains duplicate variable key "${value.key}"`);
+        }
+        keys.add(value.key);
+        if (value.value !== void 0 && typeof value.value !== "string") {
+          throw new Error(`${valueLabel}.value must be a string when provided`);
+        }
+        if (value.type !== void 0 && value.type !== "default" && value.type !== "secret") {
+          throw new Error(`${valueLabel}.type must be "default" or "secret"`);
+        }
+        if (value.enabled !== void 0 && typeof value.enabled !== "boolean") {
+          throw new Error(`${valueLabel}.enabled must be a boolean when provided`);
+        }
+        const type = value.type ?? "default";
+        const normalizedValue = value.value ?? "";
+        if (type === "secret" && normalizedValue) {
+          throw new Error(`${valueLabel} cannot contain a populated secret value; inject it at runtime`);
+        }
+        return { key: value.key, value: normalizedValue, type, enabled: value.enabled ?? true };
+      });
+    }
+    if (rich && !/^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/.test(slug)) {
+      throw new Error(`${label} rich slug must use only letters, numbers, dots, hyphens, or underscores`);
+    }
+    if (rich && Object.prototype.hasOwnProperty.call(Object.prototype, slug)) {
+      throw new Error(`${label} rich slug conflicts with a reserved object property`);
+    }
+    if (rich && /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(slug)) {
+      throw new Error(`${label} rich slug conflicts with a Windows device name`);
+    }
+    if (!rich && !slug.trim()) {
+      throw new Error(`${label} slug must be a non-empty string`);
+    }
+    const priorWasRich = seen.get(slug);
+    if (priorWasRich !== void 0 && (rich || priorWasRich)) {
+      throw new Error(`environments-json contains duplicate slug "${slug}"`);
+    }
+    if (priorWasRich === void 0) seen.set(slug, rich);
+    environments.push(slug);
+  });
+  return { environments, definitions };
+}
+function normalizeProgrammaticEnvironmentDefinitions(inputs) {
+  const definitions = inputs.environmentDefinitions;
+  if (!definitions) return inputs;
+  const prototype = Object.getPrototypeOf(definitions);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new Error("environmentDefinitions must be a plain object");
+  }
+  const entries = inputs.environments.map(
+    (slug) => Object.prototype.hasOwnProperty.call(definitions, slug) ? { slug, values: definitions[slug] } : slug
+  );
+  let raw;
+  try {
+    raw = JSON.stringify(entries);
+  } catch {
+    throw new Error("environmentDefinitions must contain JSON-serializable values");
   }
-  return parsed.map((entry) => String(entry));
+  const parsed = parseEnvironmentInputs(raw);
+  return { ...inputs, environments: parsed.environments, environmentDefinitions: parsed.definitions };
 }
 function readInput(actionCore, name, required = false) {
   return actionCore.getInput(name, { required }).trim();
@@ -129696,7 +129831,7 @@ function resolveInputs(env = process.env) {
     },
     env
   );
-  const environments = parseJsonArray(getInput2("environments-json", env) || '["prod"]');
+  const parsedEnvironments = parseEnvironmentInputs(getInput2("environments-json", env) || '["prod"]');
   const secretsResolverProvider = parseSecretsResolverProvider(getInput2("secrets-resolver", env));
   const systemEnvMap = parseJsonMap(getInput2("system-env-map-json", env) || "{}");
   const environmentUids = parseJsonMap(getInput2("environment-uids-json", env) || "{}");
@@ -129734,7 +129869,8 @@ function resolveInputs(env = process.env) {
     secretsResolverProvider,
     specSyncMode: normalizeSpecSyncMode(getInput2("spec-sync-mode", env) || "update"),
     releaseLabel: normalizeReleaseLabel(getInput2("release-label", env)) || void 0,
-    environments: environments.length > 0 ? environments : ["prod"],
+    environments: parsedEnvironments.environments.length > 0 ? parsedEnvironments.environments : ["prod"],
+    environmentDefinitions: parsedEnvironments.definitions,
     repoUrl: repoContext.repoUrl || "",
     integrationBackend: getInput2("integration-backend", env) || "bifrost",
     workspaceLinkEnabled: parseBooleanInput(getInput2("workspace-link-enabled", env), true),
@@ -130402,7 +130538,8 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
         }
       } catch {
       }
-      const values2 = buildEnvironmentValues(envName, runtimeUrl, {
+      const definedValues2 = inputs.environmentDefinitions?.[envName];
+      const values2 = definedValues2 ? definedValues2.map((value) => ({ ...value })) : buildEnvironmentValues(envName, runtimeUrl, {
         secretsResolverProvider: inputs.secretsResolverProvider,
         preservedCredentialValues: priorValues
       });
@@ -130425,7 +130562,8 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
       dependencies.core.setOutput("environment-uids-json", JSON.stringify(envUids));
       continue;
     }
-    const values = buildEnvironmentValues(envName, runtimeUrl, {
+    const definedValues = inputs.environmentDefinitions?.[envName];
+    const values = definedValues ? definedValues.map((value) => ({ ...value })) : buildEnvironmentValues(envName, runtimeUrl, {
       secretsResolverProvider: inputs.secretsResolverProvider
     });
     if (assetMarker) values.push({ key: "x-pm-onboarding", value: JSON.stringify(assetMarker), type: "default" });
@@ -131209,13 +131347,14 @@ function applyPrivateMockPrebuiltPlans(plans) {
   }
 }
 async function preparePrivateMockCloudCollection(role, collectionId, postman) {
-  const col = await postman.getCollection(collectionId);
-  const { collection } = applyPrivateMockExportCleanup(col, {
+  const snapshot = await postman.getCollection(collectionId);
+  const v3Collection = convertV2CollectionToV3Collection(snapshot);
+  const { collection } = applyPrivateMockExportCleanup(v3Collection, {
     stripManagedBlocks: isPrivateMockLegacyExportCleanupEnabled()
   });
   if (!verifyPrivateMockRootHook(collection)) {
     throw new Error(
-      `PRIVATE_MOCK_AUTH_ROOT_UNVERIFIED: Managed root hook missing from exported ${role} collection ${collectionId}`
+      `PRIVATE_MOCK_AUTH_ROOT_UNVERIFIED: Managed root hook missing from populated ${role} collection snapshot ${collectionId}`
     );
   }
   return collection;
@@ -131261,7 +131400,7 @@ async function acquireCollectionArtifact(options) {
     return { reusePrebuilt: true };
   }
   if (entry) {
-    core.info(privateMockAuth ? `Private mock has no locally reconciled exact prebuilt ${role} collection; exporting from cloud` : `Prebuilt ${role} collection entry present but did not exactly match; exporting from cloud`);
+    core.info(privateMockAuth ? `Private mock has no locally reconciled exact prebuilt ${role} collection; reading populated cloud snapshot` : `Prebuilt ${role} collection entry present but did not exactly match; reading populated cloud snapshot`);
   }
   const cloud = privateMockAuth ? await preparePrivateMockCloudCollection(role, collectionId, postman) : await postman.getCollection(collectionId);
   return { reusePrebuilt: false, cloudCollection: cloud };
@@ -131615,6 +131754,7 @@ async function commitAndPushGeneratedFiles(inputs, dependencies, privateMockAuth
   };
 }
 async function runRepoSync(inputs, dependencies, executionContext) {
+  inputs = normalizeProgrammaticEnvironmentDefinitions(inputs);
   const telemetry = createTelemetryContext({ action: "postman-repo-sync-action", actionVersion: resolveActionVersion2(), logger: dependencies.core });
   telemetry.setTeamId(dependencies.teamId);
   const logger = resolveRepoSyncLogger(dependencies);
@@ -132508,9 +132648,9 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     getEnvironment: gatewayAssets.getEnvironment.bind(gatewayAssets),
     updateEnvironment: gatewayAssets.updateEnvironment.bind(gatewayAssets),
     findEnvironmentByName: gatewayAssets.findEnvironmentByName.bind(gatewayAssets),
-    // Collection read via the v3 export endpoint — returns canonical v3 IR,
-    // written to disk by `convertAndSplitAnyCollection`. PMAK is never used for
-    // collection reads.
+    // Collection read via one retry-free populated Sync GET — returns a full
+    // v2.1 snapshot that the official runtime.models transform converts to v3
+    // before repository materialization. PMAK is never used for reads.
     getCollection: gatewayAssets.getCollection.bind(gatewayAssets),
     // Mocks via the `mock` service, collection-based monitors via the `monitors`
     // service (jobTemplates). Both reference the collection by its full public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cs/onboarding-repo-sync",
-  "version": "2.10.8",
+  "version": "2.11.0",
   "description": "Postman repo sync GitHub Action.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -25,6 +25,7 @@
     "verify:dist:assert": "npm run verify:dist:shape && npm run verify:dist:parity",
     "verify:dist": "npm run build && npm run verify:dist:assert",
     "docs:tables": "node scripts/render-action-tables.mjs",
+    "docs:pins": "node scripts/check-doc-pins.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run --exclude tests/ci-workflow-template.test.ts && vitest run tests/ci-workflow-template.test.ts && node --test .github/scripts/dispatch-e2e-monitor.test.mjs .github/scripts/prefetch-vendored-deps.test.mjs .github/scripts/verify-e2e-release.test.mjs",