@postman-cse/onboarding-repo-sync 2.1.5 → 2.1.6

package/dist/action.cjs

@@ -92333,11 +92333,11 @@ var require_valid = __commonJS({
 var require_clean = __commonJS({
   "node_modules/postman-collection/node_modules/semver/functions/clean.js"(exports2, module2) {
     var parse2 = require_parse5();
-    var clean = (version2, options) => {
+    var clean2 = (version2, options) => {
       const s = parse2(version2.trim().replace(/^[=v]+/, ""), options);
       return s ? s.version : null;
     };
-    module2.exports = clean;
+    module2.exports = clean2;
   }
 });
 
@@ -93648,7 +93648,7 @@ var require_semver2 = __commonJS({
     var identifiers = require_identifiers();
     var parse2 = require_parse5();
     var valid = require_valid();
-    var clean = require_clean();
+    var clean2 = require_clean();
     var inc = require_inc();
     var diff = require_diff();
     var major = require_major();
@@ -93686,7 +93686,7 @@ var require_semver2 = __commonJS({
     module2.exports = {
       parse: parse2,
       valid,
-      clean,
+      clean: clean2,
       inc,
       diff,
       major,
@@ -122063,7 +122063,7 @@ function getIDToken(aud) {
 }
 
 // src/index.ts
-var import_node_fs3 = require("node:fs");
+var import_node_fs4 = require("node:fs");
 var path8 = __toESM(require("node:path"), 1);
 
 // node_modules/js-yaml/dist/js-yaml.mjs
@@ -125186,6 +125186,9 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     "    branches: [main]",
     "  schedule:",
     '    - cron: "0 */6 * * *"',
+    "concurrency:",
+    "  group: postman-onboard-${{ github.head_ref || github.ref_name }}",
+    "  cancel-in-progress: false",
     "jobs:",
     "  test:",
     "    runs-on: ubuntu-latest",
@@ -125202,7 +125205,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     "          ruby <<'RUBY'",
     "          require 'yaml'",
     "          config = YAML.load_file('.postman/resources.yaml') || {}",
-    "          cloud = config.fetch('cloudResources', {})",
+    "          cloud = config.fetch('canonical', config.fetch('cloudResources', {}))",
     "          collections = cloud.fetch('collections', {})",
     "          environments = cloud.fetch('environments', {})",
     "          smoke = collections.find { |path, _| path.include?('[Smoke]') }&.last",
@@ -125400,6 +125403,58 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     ""
   ];
 }
+function renderGcWorkflowTemplate() {
+  return [
+    "name: Postman Preview GC",
+    "on:",
+    "  delete:",
+    '    branches: ["**"]',
+    "  pull_request:",
+    "    types: [closed]",
+    "  schedule:",
+    '    - cron: "0 2 * * *"',
+    "  workflow_dispatch:",
+    "    inputs:",
+    "      branch:",
+    "        description: Branch name to GC (optional, otherwise sweep by TTL/branch-existence)",
+    "        required: false",
+    "concurrency:",
+    "  group: postman-preview-gc-${{ github.ref_name }}",
+    "  cancel-in-progress: false",
+    "jobs:",
+    "  gc:",
+    "    runs-on: ubuntu-latest",
+    "    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository",
+    "    steps:",
+    "      - uses: actions/checkout@v5",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - name: Run Postman preview GC (provider-neutral cli.cjs gc)",
+    "        env:",
+    "          POSTMAN_API_KEY: ${{ secrets.POSTMAN_API_KEY }}",
+    "          POSTMAN_ACCESS_TOKEN: ${{ secrets.POSTMAN_ACCESS_TOKEN }}",
+    "          POSTMAN_WORKSPACE_ID: ${{ vars.POSTMAN_WORKSPACE_ID }}",
+    "          REPO_URL: https://github.com/${{ github.repository }}",
+    "        run: |",
+    "          set -euo pipefail",
+    "          # The repo-sync action bundles a provider-neutral gc command (cli.cjs gc)",
+    "          # that uses the Postman access token for inventory/deletion and the",
+    "          # provider ambient credential (GITHUB_TOKEN via git ls-remote) for branch existence.",
+    "          # Daily scheduled run is the retention executor (TTL contract of last resort).",
+    '          if [ -n "${{ inputs.branch }}" ]; then',
+    '            npx @postman-cse/onboarding-repo-sync gc --branch "${{ inputs.branch }}" --workspace-id "$POSTMAN_WORKSPACE_ID" --repo-url "$REPO_URL"',
+    "          else",
+    '            npx @postman-cse/onboarding-repo-sync gc --workspace-id "$POSTMAN_WORKSPACE_ID" --repo-url "$REPO_URL"',
+    "          fi",
+    "      - name: Orphan audit summary (job summary)",
+    "        if: always()",
+    "        run: |",
+    '          echo "### Preview GC orphan audit" >> "$GITHUB_STEP_SUMMARY"',
+    '          echo "Marker-guarded deletion only \u2014 strangers (no marker) are never deleted. See gc-summary-json for structured counts." >> "$GITHUB_STEP_SUMMARY"',
+    ""
+  ].join("\n");
+}
+var GC_WORKFLOW_TEMPLATE = renderGcWorkflowTemplate();
 function getCiWorkflowTemplate(provider, options = {}) {
   if (provider === "azure-devops") {
     const rawUrl = String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
@@ -126970,6 +127025,53 @@ function createInternalIntegrationAdapter(options) {
   return new BifrostInternalIntegrationAdapter(options);
 }
 
+// src/lib/retry.ts
+function sleep(delayMs) {
+  return new Promise((resolve3) => {
+    setTimeout(resolve3, delayMs);
+  });
+}
+function normalizeRetryOptions(options) {
+  return {
+    maxAttempts: Math.max(1, options.maxAttempts ?? 3),
+    delayMs: Math.max(0, options.delayMs ?? 2e3),
+    backoffMultiplier: Math.max(1, options.backoffMultiplier ?? 1),
+    maxDelayMs: options.maxDelayMs === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, options.maxDelayMs),
+    onRetry: options.onRetry ?? (async () => void 0),
+    shouldRetry: options.shouldRetry ?? (() => true),
+    sleep: options.sleep ?? sleep
+  };
+}
+async function retry(operation, options = {}) {
+  const normalized = normalizeRetryOptions(options);
+  let nextDelayMs = normalized.delayMs;
+  for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error2) {
+      const shouldRetry = attempt < normalized.maxAttempts && normalized.shouldRetry(error2, {
+        attempt,
+        maxAttempts: normalized.maxAttempts
+      });
+      if (!shouldRetry) {
+        throw error2;
+      }
+      await normalized.onRetry({
+        attempt,
+        maxAttempts: normalized.maxAttempts,
+        delayMs: nextDelayMs,
+        error: error2
+      });
+      await normalized.sleep(nextDelayMs);
+      nextDelayMs = Math.min(
+        normalized.maxDelayMs,
+        Math.round(nextDelayMs * normalized.backoffMultiplier)
+      );
+    }
+  }
+  throw new Error("Retry exhausted without returning or throwing");
+}
+
 // src/contracts.ts
 var postmanRepoSyncActionContract = {
   name: "postman-repo-sync-action",
@@ -127139,6 +127241,25 @@ var postmanRepoSyncActionContract = {
       default: "warn",
       allowedValues: ["enforce", "warn"]
     },
+    "branch-strategy": {
+      description: "Branch-aware sync strategy. legacy (default) keeps branch-blind behavior; publish-gate restricts canonical writes to the canonical branch and skips repo-sync on other branches; preview additionally maintains suffixed per-branch preview asset sets.",
+      required: false,
+      default: "legacy",
+      allowedValues: ["legacy", "preview", "publish-gate"]
+    },
+    "canonical-branch": {
+      description: "Explicit canonical branch (the sole writer of canonical assets and tracked state). Defaults to the provider-resolved default branch; required on providers without a default-branch variable (Bitbucket, Azure DevOps) when branch-strategy is not legacy.",
+      required: false
+    },
+    "channels": {
+      description: 'Comma-separated channel map for long-lived promotion branches, e.g. "develop=DEV, staging=STAGE, release/*=RC". Channel branches maintain prefix-named parallel asset sets and never mutate canonical assets.',
+      required: false
+    },
+    "preview-ttl": {
+      description: "Sliding TTL in days for preview asset sets (refreshed on every successful preview sync; the retention contract of last resort when no provider credential is available for branch-existence checks).",
+      required: false,
+      default: "30"
+    },
     "github-token": {
       description: "GitHub token used for repo variable persistence and commits.",
       required: false
@@ -127176,6 +127297,11 @@ var postmanRepoSyncActionContract = {
       description: "Spec UID from bootstrap, persisted into .postman/resources.yaml cloudResources.",
       required: false
     },
+    "spec-content-changed": {
+      description: "Whether bootstrap changed canonical spec content; controls final native Spec Hub tag publication.",
+      required: false,
+      default: "true"
+    },
     "spec-path": {
       description: "Optional repo-root-relative path to the local spec file for resources/workflows metadata.",
       required: false
@@ -127220,6 +127346,18 @@ var postmanRepoSyncActionContract = {
     },
     "commit-sha": {
       description: "Commit SHA produced by repo-write-mode, if any."
+    },
+    "sync-status": {
+      description: "Branch-aware sync status: synced, skipped-branch-gate, or empty under branch-strategy legacy."
+    },
+    "branch-decision": {
+      description: "Serialized BranchDecision JSON for downstream actions (also exported as POSTMAN_BRANCH_DECISION)."
+    },
+    "spec-version-tag": {
+      description: "Native Spec Hub version tag created after successful canonical repo-sync finalization."
+    },
+    "spec-version-url": {
+      description: "Read-only URL for the tagged Spec Hub snapshot."
     }
   },
   behavior: {
@@ -127287,53 +127425,6 @@ var PostmanAssetsClient = class {
   }
 };
 
-// src/lib/retry.ts
-function sleep(delayMs) {
-  return new Promise((resolve3) => {
-    setTimeout(resolve3, delayMs);
-  });
-}
-function normalizeRetryOptions(options) {
-  return {
-    maxAttempts: Math.max(1, options.maxAttempts ?? 3),
-    delayMs: Math.max(0, options.delayMs ?? 2e3),
-    backoffMultiplier: Math.max(1, options.backoffMultiplier ?? 1),
-    maxDelayMs: options.maxDelayMs === void 0 ? Number.POSITIVE_INFINITY : Math.max(0, options.maxDelayMs),
-    onRetry: options.onRetry ?? (async () => void 0),
-    shouldRetry: options.shouldRetry ?? (() => true),
-    sleep: options.sleep ?? sleep
-  };
-}
-async function retry(operation, options = {}) {
-  const normalized = normalizeRetryOptions(options);
-  let nextDelayMs = normalized.delayMs;
-  for (let attempt = 1; attempt <= normalized.maxAttempts; attempt += 1) {
-    try {
-      return await operation();
-    } catch (error2) {
-      const shouldRetry = attempt < normalized.maxAttempts && normalized.shouldRetry(error2, {
-        attempt,
-        maxAttempts: normalized.maxAttempts
-      });
-      if (!shouldRetry) {
-        throw error2;
-      }
-      await normalized.onRetry({
-        attempt,
-        maxAttempts: normalized.maxAttempts,
-        delayMs: nextDelayMs,
-        error: error2
-      });
-      await normalized.sleep(nextDelayMs);
-      nextDelayMs = Math.min(
-        normalized.maxDelayMs,
-        Math.round(nextDelayMs * normalized.backoffMultiplier)
-      );
-    }
-  }
-  throw new Error("Retry exhausted without returning or throwing");
-}
-
 // src/lib/postman/postman-gateway-assets-client.ts
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
@@ -127359,6 +127450,84 @@ var PostmanGatewayAssetsClient = class {
     if (!envelope) return null;
     return this.asRecord(envelope.data) ?? envelope;
   }
+  /** Native Spec Hub tags attach to the latest changelog group. */
+  async tagSpecVersion(specId, name) {
+    const trimmed = name.trim().slice(0, 255);
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "post",
+      path: `/specifications/${specId}/tags`,
+      body: { name: trimmed }
+    });
+    const record = this.dataOf(response) ?? {};
+    return { id: String(record.id ?? "").trim(), name: String(record.name ?? trimmed).trim() };
+  }
+  async listSpecVersionTags(specId) {
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/tags`,
+      query: { limit: "50" }
+    });
+    const data = Array.isArray(response?.data) ? response.data : [];
+    return data.map((entry) => this.asRecord(entry)).filter((entry) => entry !== null).map((entry) => ({
+      id: String(entry.id ?? "").trim(),
+      // listTags returns `message`; createTag returns `name`. Accept both.
+      name: String(entry.name ?? entry.message ?? "").trim()
+    })).filter((entry) => entry.id || entry.name);
+  }
+  async deleteCollection(collectionUid) {
+    const bareId = String(collectionUid).split("-").slice(-5).join("-") || collectionUid;
+    await this.gateway.requestJson({
+      service: "collection",
+      method: "delete",
+      path: `/v3/collections/${bareId}`
+    });
+  }
+  async listSpecifications(workspaceId) {
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications?containerType=workspace&containerId=${workspaceId}`
+    });
+    const data = Array.isArray(response?.data) ? response.data : [];
+    return data.map((entry) => this.asRecord(entry)).filter((entry) => entry !== null).map((entry) => ({ uid: String(entry.id ?? entry.uid ?? "").trim(), name: String(entry.name ?? "").trim() })).filter((entry) => entry.uid && entry.name);
+  }
+  async getSpecContent(specId) {
+    const files = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/files`
+    });
+    const entries = Array.isArray(files?.data) ? files.data : [];
+    const root = entries.map((entry) => this.asRecord(entry)).find((entry) => entry?.type === "ROOT") ?? entries.map((entry) => this.asRecord(entry)).find((entry) => entry !== null);
+    const fileId = String(root?.id ?? "").trim();
+    if (!fileId) return void 0;
+    const file = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/files/${fileId}`,
+      query: { fields: "content" }
+    });
+    const record = this.dataOf(file);
+    return typeof record?.content === "string" ? record.content : void 0;
+  }
+  async listSpecCollections(specId) {
+    const response = await this.gateway.requestJson({
+      service: "specification",
+      method: "get",
+      path: `/specifications/${specId}/collections`
+    });
+    const data = Array.isArray(response?.data) ? response.data : [];
+    return data.map((entry) => this.asRecord(entry)).filter((entry) => entry !== null).map((entry) => ({ uid: String(entry.collection ?? entry.collectionId ?? entry.id ?? "").trim(), name: String(entry.name ?? "").trim() })).filter((entry) => entry.uid);
+  }
+  async deleteSpec(specId) {
+    await this.gateway.requestJson({
+      service: "specification",
+      method: "delete",
+      path: `/specifications/${specId}`
+    });
+  }
   idOf(record) {
     if (!record) return "";
     const id = record.uid ?? record.id;
@@ -127643,6 +127812,9 @@ var PostmanGatewayAssetsClient = class {
             path: `/mocks?workspace=${ws}`,
             body
           },
+          // Unsafe create: never blind re-POST. An ESOCKETTIMEDOUT after accept
+          // may still have created the mock; reconcile via discovery below and
+          // let the orchestrator retry the whole create-or-adopt cycle.
           { retryTransient: false }
         );
         const record = this.dataOf(response);
@@ -127681,6 +127853,33 @@ var PostmanGatewayAssetsClient = class {
       environment: String(m.environment ?? "")
     }));
   }
+  /**
+   * Delete an environment through the sync service (GC path). The path id is
+   * the bare model id (public uid tail), mirroring updateEnvironment.
+   */
+  async deleteEnvironment(uid) {
+    await this.gateway.requestJson({
+      service: "sync",
+      method: "delete",
+      path: `/environment/${this.toModelId(uid)}`
+    });
+  }
+  /** Delete a mock server (GC path). */
+  async deleteMock(uid) {
+    await this.gateway.requestJson({
+      service: "mock",
+      method: "delete",
+      path: `/mocks/${this.toModelId(uid)}`
+    });
+  }
+  /** Delete a collection-based monitor (jobTemplate) (GC path). */
+  async deleteMonitor(uid) {
+    await this.gateway.requestJson({
+      service: "monitors",
+      method: "delete",
+      path: `/jobTemplates/${this.toModelId(uid)}`
+    });
+  }
   async mockExists(uid) {
     try {
       await this.gateway.requestJson({
@@ -128187,6 +128386,331 @@ function validateCertMaterial(certBase64, keyBase64, passphrase) {
   }
 }
 
+// src/lib/repo/branch-decision.ts
+var import_node_fs3 = require("node:fs");
+var import_node_crypto3 = require("node:crypto");
+var ContractError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = "ContractError";
+  }
+};
+function clean(value) {
+  const trimmed = (value ?? "").trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function stripRefPrefix(ref) {
+  const raw = clean(ref);
+  if (!raw) {
+    return { kind: "unknown" };
+  }
+  if (raw.startsWith("refs/heads/")) {
+    return { name: raw.slice("refs/heads/".length), kind: "branch" };
+  }
+  if (raw.startsWith("refs/tags/")) {
+    return { name: raw.slice("refs/tags/".length), kind: "tag" };
+  }
+  if (raw.startsWith("refs/pull/") || raw.startsWith("refs/merge")) {
+    return { kind: "unknown" };
+  }
+  return { name: raw, kind: "branch" };
+}
+function detectProvider(env) {
+  if (clean(env.GITHUB_ACTIONS) || clean(env.GITHUB_REPOSITORY)) return "github";
+  if (clean(env.GITLAB_CI) || clean(env.CI_PROJECT_PATH)) return "gitlab";
+  if (clean(env.BITBUCKET_REPO_SLUG) || clean(env.BITBUCKET_BRANCH)) return "bitbucket";
+  if (clean(env.TF_BUILD) || clean(env.BUILD_REPOSITORY_URI)) return "azure-devops";
+  return "unknown";
+}
+function readGithubEvent(env) {
+  const path9 = clean(env.GITHUB_EVENT_PATH);
+  if (!path9) return void 0;
+  try {
+    return JSON.parse((0, import_node_fs3.readFileSync)(path9, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function resolveBranchIdentity(env = process.env, overrides = {}) {
+  const provider = detectProvider(env);
+  const explicitDefault = clean(overrides.defaultBranch);
+  let headBranch;
+  let rawRef;
+  let refKind;
+  let isPrContext = false;
+  let isForkPr = false;
+  let defaultBranch = explicitDefault;
+  let headSha;
+  switch (provider) {
+    case "github": {
+      const event = readGithubEvent(env);
+      headSha = clean(env.GITHUB_SHA);
+      defaultBranch ??= clean(event?.repository?.default_branch);
+      const headRef = clean(env.GITHUB_HEAD_REF);
+      if (headRef) {
+        isPrContext = true;
+        headBranch = headRef;
+        rawRef = clean(env.GITHUB_REF) ?? headRef;
+        refKind = "branch";
+        const headRepo = event?.pull_request?.head?.repo?.full_name;
+        const baseRepo = event?.pull_request?.base?.repo?.full_name ?? event?.repository?.full_name;
+        isForkPr = Boolean(headRepo && baseRepo && headRepo !== baseRepo);
+        headSha = clean(event?.pull_request?.head?.sha) ?? headSha;
+      } else {
+        rawRef = clean(env.GITHUB_REF) ?? clean(env.GITHUB_REF_NAME);
+        const parsed = stripRefPrefix(rawRef);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        refKind = parsed.kind;
+      }
+      break;
+    }
+    case "gitlab": {
+      headSha = clean(env.CI_COMMIT_SHA);
+      defaultBranch ??= clean(env.CI_DEFAULT_BRANCH);
+      const mrSource = clean(env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME);
+      if (mrSource) {
+        isPrContext = true;
+        headBranch = mrSource;
+        rawRef = mrSource;
+        refKind = "branch";
+        const sourceProject = clean(env.CI_MERGE_REQUEST_SOURCE_PROJECT_ID);
+        const targetProject = clean(env.CI_MERGE_REQUEST_PROJECT_ID);
+        isForkPr = Boolean(sourceProject && targetProject && sourceProject !== targetProject);
+      } else if (clean(env.CI_COMMIT_TAG)) {
+        rawRef = clean(env.CI_COMMIT_TAG);
+        refKind = "tag";
+      } else {
+        headBranch = clean(env.CI_COMMIT_BRANCH) ?? clean(env.CI_COMMIT_REF_NAME);
+        rawRef = headBranch;
+        refKind = headBranch ? "branch" : "unknown";
+      }
+      break;
+    }
+    case "bitbucket": {
+      headSha = clean(env.BITBUCKET_COMMIT);
+      if (clean(env.BITBUCKET_TAG)) {
+        rawRef = clean(env.BITBUCKET_TAG);
+        refKind = "tag";
+      } else {
+        headBranch = clean(env.BITBUCKET_BRANCH);
+        rawRef = headBranch;
+        refKind = headBranch ? "branch" : "unknown";
+        isPrContext = Boolean(clean(env.BITBUCKET_PR_ID));
+      }
+      break;
+    }
+    case "azure-devops": {
+      headSha = clean(env.BUILD_SOURCEVERSION);
+      const prSource = clean(env.SYSTEM_PULLREQUEST_SOURCEBRANCH);
+      if (prSource) {
+        isPrContext = true;
+        const parsed = stripRefPrefix(prSource);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        rawRef = prSource;
+        refKind = parsed.kind;
+        const forkFlag = clean(env.SYSTEM_PULLREQUEST_ISFORK);
+        isForkPr = forkFlag?.toLowerCase() === "true";
+      } else {
+        rawRef = clean(env.BUILD_SOURCEBRANCH);
+        const parsed = stripRefPrefix(rawRef);
+        headBranch = parsed.kind === "branch" ? parsed.name : void 0;
+        refKind = parsed.kind;
+      }
+      break;
+    }
+    default: {
+      refKind = "unknown";
+    }
+  }
+  if (refKind === "branch" && headBranch && defaultBranch && headBranch === defaultBranch) {
+    refKind = "default-branch";
+  }
+  return { provider, headBranch, rawRef, defaultBranch, refKind, isPrContext, isForkPr, headSha };
+}
+function parseChannelRules(input) {
+  const raw = clean(input);
+  const rules = [];
+  for (const part of raw ? raw.split(",") : []) {
+    const entry = part.trim();
+    if (!entry) continue;
+    const eq = entry.indexOf("=");
+    if (eq <= 0 || eq === entry.length - 1) {
+      throw new ContractError(
+        "CONTRACT_CHANNELS_INPUT_INVALID",
+        `channels entry "${entry}" must be <branch-or-glob>=<CODE>`
+      );
+    }
+    const pattern = entry.slice(0, eq).trim();
+    const code = entry.slice(eq + 1).trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9_-]{0,15}$/.test(code)) {
+      throw new ContractError(
+        "CONTRACT_CHANNELS_INPUT_INVALID",
+        `channel code "${code}" must be 1-16 chars, A-Z 0-9 _ -, starting with a letter`
+      );
+    }
+    rules.push({ pattern, code });
+  }
+  if (!rules.some((rule) => rule.pattern === "release/*")) {
+    rules.push({ pattern: "release/*", code: "RC" });
+  }
+  return rules;
+}
+function matchChannel(branch, rules) {
+  for (const rule of rules) {
+    if (rule.pattern.endsWith("*")) {
+      const prefix = rule.pattern.slice(0, -1);
+      if (branch.startsWith(prefix)) return rule;
+    } else if (branch === rule.pattern) {
+      return rule;
+    }
+  }
+  return void 0;
+}
+function resolveBranchDecision(options) {
+  const { strategy, identity } = options;
+  const channels = options.channels ?? [];
+  if (strategy === "legacy") {
+    return {
+      tier: "legacy",
+      strategy,
+      identity,
+      canonicalBranch: clean(options.canonicalBranch) ?? identity.defaultBranch,
+      reason: "branch-strategy legacy: branch-blind pre-v2 behavior"
+    };
+  }
+  const canonicalBranch = clean(options.canonicalBranch) ?? identity.defaultBranch;
+  if (!canonicalBranch) {
+    throw new ContractError(
+      "CONTRACT_DEFAULT_BRANCH_UNRESOLVED",
+      `cannot resolve the canonical branch on ${identity.provider} (no explicit canonical-branch input and the provider exposes no default-branch variable). Set the canonical-branch input.`
+    );
+  }
+  if (identity.refKind === "tag" || identity.refKind === "unknown" || !identity.headBranch) {
+    return {
+      tier: "gated",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `ref kind ${identity.refKind}: never canonical/preview-eligible; no-op with annotation`
+    };
+  }
+  if (identity.headBranch === canonicalBranch) {
+    return {
+      tier: "canonical",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `head branch equals canonical branch ${canonicalBranch}`
+    };
+  }
+  const channel = matchChannel(identity.headBranch, channels);
+  if (channel) {
+    return {
+      tier: "channel",
+      strategy,
+      identity,
+      canonicalBranch,
+      channel,
+      reason: `branch ${identity.headBranch} matches channel ${channel.pattern}=${channel.code}`
+    };
+  }
+  if (strategy === "preview") {
+    if (identity.isForkPr) {
+      return {
+        tier: "gated",
+        strategy,
+        identity,
+        canonicalBranch,
+        reason: "fork PR: preview-ineligible (same-repo gate), gated instead"
+      };
+    }
+    return {
+      tier: "preview",
+      strategy,
+      identity,
+      canonicalBranch,
+      reason: `branch ${identity.headBranch} under branch-strategy preview`
+    };
+  }
+  return {
+    tier: "gated",
+    strategy,
+    identity,
+    canonicalBranch,
+    reason: `branch ${identity.headBranch} under branch-strategy publish-gate`
+  };
+}
+var BRANCH_DECISION_ENV = "POSTMAN_BRANCH_DECISION";
+function serializeBranchDecision(decision) {
+  return JSON.stringify(decision);
+}
+function parseBranchDecision(raw) {
+  const value = clean(raw);
+  if (!value) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new ContractError("CONTRACT_BRANCH_DECISION_INVALID", "POSTMAN_BRANCH_DECISION is not valid JSON");
+  }
+  const candidate = parsed;
+  const tiers = ["canonical", "channel", "preview", "gated", "legacy"];
+  if (!candidate || typeof candidate !== "object" || !tiers.includes(candidate.tier) || !candidate.identity) {
+    throw new ContractError("CONTRACT_BRANCH_DECISION_INVALID", "POSTMAN_BRANCH_DECISION does not carry a valid BranchDecision");
+  }
+  return candidate;
+}
+function resolveEffectiveBranchDecision(options, env = process.env) {
+  const inherited = parseBranchDecision(env[BRANCH_DECISION_ENV]);
+  if (inherited) return inherited;
+  return resolveBranchDecision(options);
+}
+var PREVIEW_SLUG_MAX = 30;
+function buildBranchSlug(rawBranch) {
+  const sanitized = rawBranch.replace(/^refs\/heads\//, "").replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
+  const truncated = sanitized.slice(0, PREVIEW_SLUG_MAX);
+  const lossy = truncated !== rawBranch.replace(/^refs\/heads\//, "");
+  if (!lossy) {
+    return { suffix: truncated, slug: truncated, lossy };
+  }
+  const hash = (0, import_node_crypto3.createHash)("sha256").update(rawBranch).digest("hex").slice(0, 6);
+  return { suffix: `${truncated}-${hash}`, slug: truncated, lossy };
+}
+function previewAssetName(baseName, rawBranch) {
+  return `${baseName} @${buildBranchSlug(rawBranch).suffix}`;
+}
+function channelAssetName(baseName, code) {
+  return `[${code}] ${baseName}`;
+}
+var MARKER_KEY = "x-pm-onboarding";
+function parseAssetMarker(description) {
+  if (!description) return void 0;
+  const index = description.indexOf(`${MARKER_KEY}:`);
+  if (index === -1) return void 0;
+  const jsonStart = description.indexOf("{", index);
+  if (jsonStart === -1) return void 0;
+  let depth = 0;
+  for (let i = jsonStart; i < description.length; i += 1) {
+    const ch = description[i];
+    if (ch === "{") depth += 1;
+    else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        try {
+          const parsed = JSON.parse(description.slice(jsonStart, i + 1));
+          if (parsed && typeof parsed === "object" && parsed.repo && parsed.role) return parsed;
+        } catch {
+          return void 0;
+        }
+        return void 0;
+      }
+    }
+  }
+  return void 0;
+}
+
 // src/index.ts
 function parseBooleanInput(value, defaultValue) {
   const normalized = String(value || "").trim().toLowerCase();
@@ -128205,16 +128729,16 @@ function getInput2(name, env = process.env) {
   const runnerRaw = runnerName === normalizedName ? void 0 : env[runnerName];
   const hasNormalized = normalizedRaw !== void 0;
   const hasRunner = runnerRaw !== void 0;
+  const normalizedValue = normalizeInputValue(normalizedRaw);
+  const runnerValue = normalizeInputValue(runnerRaw);
   if (hasNormalized && hasRunner) {
-    const normalizedValue = normalizeInputValue(normalizedRaw);
-    const runnerValue = normalizeInputValue(runnerRaw);
-    if (normalizedValue !== runnerValue) {
+    if (normalizedValue && runnerValue && normalizedValue !== runnerValue) {
       throw new Error(
         `Conflicting values for ${name}: ${normalizedName}=${JSON.stringify(normalizedValue)} vs ${runnerName}=${JSON.stringify(runnerValue)}`
       );
     }
   }
-  return normalizeInputValue(hasNormalized ? normalizedRaw : runnerRaw);
+  return normalizedValue || runnerValue;
 }
 function hasInput(name, env = process.env) {
   const normalizedName = `INPUT_${name.replace(/-/g, "_").toUpperCase()}`;
@@ -128276,6 +128800,17 @@ function parseCredentialPreflight(value) {
     `Unsupported credential-preflight "${normalized}". Supported values: ${allowed.join(", ")}`
   );
 }
+function parseBranchStrategy(value) {
+  const definition = postmanRepoSyncActionContract.inputs["branch-strategy"];
+  const allowed = definition.allowedValues ?? [];
+  const normalized = String(value || "").trim() || (definition.default ?? "legacy");
+  if (allowed.includes(normalized)) {
+    return normalized;
+  }
+  throw new Error(
+    `Unsupported branch-strategy "${normalized}". Supported values: ${allowed.join(", ")}`
+  );
+}
 function normalizeReleaseLabel(value) {
   const cleaned = normalizeInputValue(value).replace(/^refs\/heads\//, "").replace(/^refs\/tags\//, "").replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
   return cleaned;
@@ -128320,6 +128855,7 @@ function resolveInputs(env = process.env) {
     smokeCollectionId: getInput2("smoke-collection-id", env),
     contractCollectionId: getInput2("contract-collection-id", env),
     specId: getInput2("spec-id", env),
+    specContentChanged: parseBooleanInput(getInput2("spec-content-changed", env), true),
     specPath: getInput2("spec-path", env),
     collectionSyncMode: normalizeCollectionSyncMode(getInput2("collection-sync-mode", env) || "refresh"),
     specSyncMode: normalizeSpecSyncMode(getInput2("spec-sync-mode", env) || "update"),
@@ -128342,6 +128878,10 @@ function resolveInputs(env = process.env) {
     postmanApiKey: getInput2("postman-api-key", env),
     postmanAccessToken: getInput2("postman-access-token", env),
     credentialPreflight: parseCredentialPreflight(getInput2("credential-preflight", env)),
+    branchStrategy: parseBranchStrategy(getInput2("branch-strategy", env)),
+    canonicalBranch: getInput2("canonical-branch", env) || void 0,
+    channels: getInput2("channels", env) || void 0,
+    previewTtlDays: Math.max(1, Number.parseInt(getInput2("preview-ttl", env) || "30", 10) || 30),
     adoToken: getInput2("ado-token", env) || normalizeInputValue(env.SYSTEM_ACCESSTOKEN),
     githubToken: getInput2("github-token", env),
     ghFallbackToken: getInput2("gh-fallback-token", env),
@@ -128368,6 +128908,40 @@ function resolveInputs(env = process.env) {
     postmanIapubBase: endpointProfile.iapubBaseUrl
   };
 }
+function buildBranchAssetMarker(decision, inputs, now = /* @__PURE__ */ new Date()) {
+  if (decision.tier !== "preview" && decision.tier !== "channel") {
+    return void 0;
+  }
+  const rawBranch = decision.identity.headBranch;
+  const repo = inputs.repoUrl || inputs.repository;
+  if (!rawBranch || !repo) {
+    return void 0;
+  }
+  const ttlMs = inputs.previewTtlDays * 24 * 60 * 60 * 1e3;
+  return {
+    repo,
+    rawBranch,
+    sanitizedBranch: buildBranchSlug(rawBranch).suffix,
+    role: decision.tier,
+    headSha: decision.identity.headSha,
+    createdAt: now.toISOString(),
+    lastSyncedAt: now.toISOString(),
+    ...decision.tier === "preview" ? { expiresAt: new Date(now.getTime() + ttlMs).toISOString() } : {}
+  };
+}
+function assertBranchAssetIds(inputs, decision, branchOwnedIds = process.env.POSTMAN_BRANCH_ASSET_IDS === "owned") {
+  if (decision.tier === "legacy" || decision.tier === "canonical" || branchOwnedIds) return;
+  const provided = [
+    ["baseline-collection-id", inputs.baselineCollectionId],
+    ["smoke-collection-id", inputs.smokeCollectionId],
+    ["contract-collection-id", inputs.contractCollectionId]
+  ].filter(([, value]) => Boolean(value));
+  if (provided.length > 0) {
+    throw new Error(
+      `CONTRACT_BRANCH_CANONICAL_WRITE: a ${decision.tier} repo-sync run cannot accept explicit collection IDs (${provided.map(([name]) => name).join(", ")}). Run bootstrap in the same branch-aware pipeline so it can produce branch-owned IDs.`
+    );
+  }
+}
 function buildEnvironmentValues(envName, baseUrl) {
   return [
     { key: "baseUrl", value: baseUrl, type: "default" },
@@ -128380,12 +128954,48 @@ function buildEnvironmentValues(envName, baseUrl) {
   ];
 }
 var LEGACY_BASELINE_COLLECTION_PREFIX = "[Baseline]";
+var RESOURCES_STATE_VERSION = 2;
+var SUPPORTED_STATE_VERSIONS = /* @__PURE__ */ new Set([1, RESOURCES_STATE_VERSION]);
+var StateUnreadableError = class extends Error {
+  code = "CONTRACT_STATE_UNREADABLE";
+  constructor(message) {
+    super(`CONTRACT_STATE_UNREADABLE: ${message}`);
+    this.name = "StateUnreadableError";
+  }
+};
 function readResourcesState() {
+  let raw;
   try {
-    return load((0, import_node_fs3.readFileSync)(".postman/resources.yaml", "utf8"));
+    raw = (0, import_node_fs4.readFileSync)(".postman/resources.yaml", "utf8");
   } catch {
     return null;
   }
+  let parsed;
+  try {
+    parsed = load(raw);
+  } catch (error2) {
+    throw new StateUnreadableError(
+      `.postman/resources.yaml exists but is not parseable YAML (${error2 instanceof Error ? error2.message : String(error2)}). Fix or delete the file; refusing to treat tracked state as absent.`
+    );
+  }
+  if (parsed === null || parsed === void 0) {
+    return null;
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new StateUnreadableError(
+      ".postman/resources.yaml exists but does not contain a YAML mapping. Fix or delete the file; refusing to treat tracked state as absent."
+    );
+  }
+  const state = parsed;
+  if (state.version !== void 0 && !SUPPORTED_STATE_VERSIONS.has(Number(state.version))) {
+    throw new StateUnreadableError(
+      `.postman/resources.yaml declares unsupported state version ${String(state.version)} (supported: 1, ${RESOURCES_STATE_VERSION}). Upgrade the action or fix the file.`
+    );
+  }
+  if (state.canonical && !state.cloudResources) {
+    state.cloudResources = { ...state.canonical };
+  }
+  return state;
 }
 function findCloudResourceId(map, matcher) {
   if (!map) {
@@ -128420,7 +129030,7 @@ function isOpenApiSpecFile(filePath) {
     return false;
   }
   try {
-    const raw = (0, import_node_fs3.readFileSync)(filePath, "utf8");
+    const raw = (0, import_node_fs4.readFileSync)(filePath, "utf8");
     const parsed = filePath.endsWith(".json") ? JSON.parse(raw) : load(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return false;
@@ -128449,7 +129059,7 @@ function scanLocalSpecReferences(baseDir = ".") {
   const found = /* @__PURE__ */ new Set();
   const refs = [];
   const visit2 = (currentDir) => {
-    for (const entry of (0, import_node_fs3.readdirSync)(currentDir, { withFileTypes: true })) {
+    for (const entry of (0, import_node_fs4.readdirSync)(currentDir, { withFileTypes: true })) {
       if (ignoredDirs.has(entry.name)) {
         continue;
       }
@@ -128479,7 +129089,7 @@ function resolveMappedSpecReference(explicitSpecPath, discoveredSpecs) {
   const normalizedExplicitPath = normalizeToPosix(explicitSpecPath.trim());
   if (normalizedExplicitPath) {
     const explicitFullPath = path8.resolve(normalizedExplicitPath);
-    if ((0, import_node_fs3.existsSync)(explicitFullPath) && (0, import_node_fs3.statSync)(explicitFullPath).isFile()) {
+    if ((0, import_node_fs4.existsSync)(explicitFullPath) && (0, import_node_fs4.statSync)(explicitFullPath).isFile()) {
       return {
         repoRelativePath: normalizedExplicitPath,
         configRelativePath: normalizeToPosix(path8.join("..", normalizedExplicitPath))
@@ -128506,7 +129116,11 @@ function createOutputs(inputs) {
     "mock-url": "",
     "monitor-id": "",
     "repo-sync-summary-json": "{}",
-    "commit-sha": ""
+    "commit-sha": "",
+    "sync-status": "",
+    "branch-decision": "",
+    "spec-version-tag": "",
+    "spec-version-url": ""
   };
 }
 function readActionInputs(actionCore) {
@@ -128551,6 +129165,10 @@ function readActionInputs(actionCore) {
     INPUT_POSTMAN_API_KEY: postmanApiKey,
     INPUT_POSTMAN_ACCESS_TOKEN: postmanAccessToken,
     INPUT_CREDENTIAL_PREFLIGHT: readInput(actionCore, "credential-preflight") || "warn",
+    INPUT_BRANCH_STRATEGY: readInput(actionCore, "branch-strategy"),
+    INPUT_CANONICAL_BRANCH: readInput(actionCore, "canonical-branch"),
+    INPUT_CHANNELS: readInput(actionCore, "channels"),
+    INPUT_PREVIEW_TTL: readInput(actionCore, "preview-ttl"),
     INPUT_ADO_TOKEN: adoToken,
     INPUT_GITHUB_TOKEN: githubToken,
     INPUT_GH_FALLBACK_TOKEN: ghFallbackToken,
@@ -128665,7 +129283,7 @@ async function persistSslSecrets(inputs, actionCore, actionExec, repository, env
     );
   }
 }
-async function upsertEnvironments(inputs, dependencies, resourcesState) {
+async function upsertEnvironments(inputs, dependencies, resourcesState, assetMarker) {
   const envUids = {
     ...getEnvironmentUidsFromResources(resourcesState),
     ...inputs.environmentUids
@@ -128675,7 +129293,6 @@ async function upsertEnvironments(inputs, dependencies, resourcesState) {
   }
   for (const envName of inputs.environments) {
     const runtimeUrl = String(inputs.envRuntimeUrls[envName] || "").trim();
-    const values = buildEnvironmentValues(envName, runtimeUrl);
     const displayName = `${inputs.projectName} - ${envName}`;
     let existingUid = String(envUids[envName] || "").trim();
     if (!existingUid) {
@@ -128691,10 +129308,27 @@ async function upsertEnvironments(inputs, dependencies, resourcesState) {
       }
     }
     if (existingUid) {
-      await dependencies.postman.updateEnvironment(existingUid, displayName, values);
+      let marker = assetMarker;
+      if (marker) {
+        try {
+          const existing = await dependencies.postman.getEnvironment(existingUid);
+          const values3 = existing.data?.values ?? existing.values ?? [];
+          const prior = values3.find((value) => value.key === "x-pm-onboarding")?.value;
+          const priorMarker = parseAssetMarker(prior ? `x-pm-onboarding: ${prior}` : void 0);
+          if (priorMarker?.repo === marker.repo && priorMarker.rawBranch === marker.rawBranch) {
+            marker = { ...marker, createdAt: priorMarker.createdAt };
+          }
+        } catch {
+        }
+      }
+      const values2 = buildEnvironmentValues(envName, runtimeUrl);
+      if (marker) values2.push({ key: "x-pm-onboarding", value: JSON.stringify(marker), type: "default" });
+      await dependencies.postman.updateEnvironment(existingUid, displayName, values2);
       envUids[envName] = existingUid;
       continue;
     }
+    const values = buildEnvironmentValues(envName, runtimeUrl);
+    if (assetMarker) values.push({ key: "x-pm-onboarding", value: JSON.stringify(assetMarker), type: "default" });
     envUids[envName] = await dependencies.postman.createEnvironment(
       inputs.workspaceId,
       displayName,
@@ -128704,7 +129338,7 @@ async function upsertEnvironments(inputs, dependencies, resourcesState) {
   return envUids;
 }
 function ensureDir(path9) {
-  (0, import_node_fs3.mkdirSync)(path9, { recursive: true });
+  (0, import_node_fs4.mkdirSync)(path9, { recursive: true });
 }
 function getCollectionDirectoryName(kind, projectName) {
   if (kind === "Baseline") {
@@ -128741,7 +129375,7 @@ function stripVolatileFields(obj) {
 }
 function writeJsonFile(path9, content, normalize3 = false) {
   const data = normalize3 ? stripVolatileFields(content) : content;
-  (0, import_node_fs3.writeFileSync)(path9, JSON.stringify(data, null, 2));
+  (0, import_node_fs4.writeFileSync)(path9, JSON.stringify(data, null, 2));
 }
 function buildMappedSpecCloudKey(mappedSource, specSyncMode, releaseLabel) {
   if (specSyncMode !== "version") {
@@ -128765,31 +129399,30 @@ function resolveDurableWorkspaceId(options) {
   }
   return prior === candidate ? prior : void 0;
 }
-function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, localSpecRefs, mappedSpecRef, specId, existingSpecs) {
-  const manifest = {};
+function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir, localSpecRefs, mappedSpecRef, specId, existingSpecs, priorState) {
+  const manifest = { ...priorState ?? {} };
+  delete manifest.version;
+  delete manifest.workspace;
+  delete manifest.localResources;
+  delete manifest.cloudResources;
+  delete manifest.canonical;
+  manifest.version = RESOURCES_STATE_VERSION;
   if (workspaceId) {
     manifest.workspace = { id: workspaceId };
   }
-  const localResources = {};
   const cloudResources = {};
   const collectionKeys = Object.keys(collectionMap);
   if (collectionKeys.length > 0) {
-    localResources.collections = collectionKeys;
     cloudResources.collections = collectionMap;
   }
   const envEntries = Object.entries(envMap);
   if (envEntries.length > 0) {
-    localResources.environments = envEntries.map(
-      ([envName]) => `../${artifactDir}/environments/${envName}.postman_environment.json`
-    );
     cloudResources.environments = {};
     for (const [envName, envUid] of envEntries) {
       cloudResources.environments[`../${artifactDir}/environments/${envName}.postman_environment.json`] = envUid;
     }
   }
-  if (localSpecRefs.length > 0) {
-    localResources.specs = localSpecRefs;
-  }
+  void localSpecRefs;
   const specs = { ...existingSpecs || {} };
   if (mappedSpecRef && specId) {
     specs[mappedSpecRef] = specId;
@@ -128797,11 +129430,8 @@ function buildResourcesManifest(workspaceId, collectionMap, envMap, artifactDir,
   if (Object.keys(specs).length > 0) {
     cloudResources.specs = specs;
   }
-  if (Object.keys(localResources).length > 0) {
-    manifest.localResources = localResources;
-  }
   if (Object.keys(cloudResources).length > 0) {
-    manifest.cloudResources = cloudResources;
+    manifest.canonical = cloudResources;
   }
   return dump(manifest, {
     lineWidth: -1,
@@ -128842,21 +129472,21 @@ function assertPathWithinCwd(targetPath, fieldName) {
   if (!rawPath || hasControlCharacter2(originalPath) || path8.isAbsolute(rawPath) || path8.win32.isAbsolute(rawPath) || segments.includes("..") || rawPath.startsWith(":") || hasControlCharacter2(rawPath)) {
     throw new Error(`${fieldName} must stay within the repository root; received ${targetPath}`);
   }
-  const base = (0, import_node_fs3.realpathSync)(process.cwd());
+  const base = (0, import_node_fs4.realpathSync)(process.cwd());
   const resolved = path8.resolve(base, rawPath);
   const relative4 = path8.relative(base, resolved);
   if (relative4.startsWith("..") || path8.isAbsolute(relative4)) {
     throw new Error(`${fieldName} must stay within the repository root; received ${targetPath}`);
   }
   let existingPath = resolved;
-  while (!(0, import_node_fs3.existsSync)(existingPath)) {
+  while (!(0, import_node_fs4.existsSync)(existingPath)) {
     const parent = path8.dirname(existingPath);
     if (parent === existingPath) {
       break;
     }
     existingPath = parent;
   }
-  const realExistingPath = (0, import_node_fs3.realpathSync)(existingPath);
+  const realExistingPath = (0, import_node_fs4.realpathSync)(existingPath);
   const realRelative = path8.relative(base, realExistingPath);
   if (realRelative.startsWith("..") || path8.isAbsolute(realRelative)) {
     throw new Error(`${fieldName} must stay within the repository root; received ${targetPath}`);
@@ -128884,8 +129514,8 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName,
   ensureDir(specsDir);
   ensureDir(".postman");
   const globalsFilePath = `${globalsDir}/workspace.globals.yaml`;
-  if (!(0, import_node_fs3.existsSync)(globalsFilePath)) {
-    (0, import_node_fs3.writeFileSync)(globalsFilePath, "name: Globals\nvalues: []\n");
+  if (!(0, import_node_fs4.existsSync)(globalsFilePath)) {
+    (0, import_node_fs4.writeFileSync)(globalsFilePath, "name: Globals\nvalues: []\n");
   }
   if (inputs.generateCiWorkflow) {
     const ciDir = inputs.ciWorkflowPath.split("/").slice(0, -1).join("/");
@@ -128932,7 +129562,7 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName,
     workspaceLinkEnabled: inputs.workspaceLinkEnabled,
     workspaceLinkStatus: options.workspaceLinkStatus
   });
-  (0, import_node_fs3.writeFileSync)(".postman/resources.yaml", buildResourcesManifest(
+  (0, import_node_fs4.writeFileSync)(".postman/resources.yaml", buildResourcesManifest(
     durableWorkspaceId,
     manifestCollections,
     envUids,
@@ -128940,10 +129570,11 @@ async function exportArtifacts(inputs, dependencies, envUids, assetProjectName,
     discoveredSpecs.map((spec) => spec.configRelativePath),
     mappedSpecCloudKey,
     inputs.specId || void 0,
-    options.existingSpecs
+    options.existingSpecs,
+    options.priorState
   ));
   if (mappedSpec && Object.keys(manifestCollections).length > 0) {
-    (0, import_node_fs3.writeFileSync)(
+    (0, import_node_fs4.writeFileSync)(
       ".postman/workflows.yaml",
       buildSpecCollectionWorkflowManifest(
         mappedSpec.configRelativePath,
@@ -128988,19 +129619,29 @@ async function commitAndPushGeneratedFiles(inputs, dependencies) {
       const dir = parts.slice(0, -1).join("/");
       ensureDir(dir);
     }
-    (0, import_node_fs3.writeFileSync)(inputs.ciWorkflowPath, ciWorkflow);
+    (0, import_node_fs4.writeFileSync)(inputs.ciWorkflowPath, ciWorkflow);
+    if (inputs.provider === "github" || inputs.provider === "unknown") {
+      const gcPath = ".github/workflows/postman-preview-gc.yml";
+      if (inputs.ciWorkflowPath.endsWith(".github/workflows/ci.yml") || inputs.ciWorkflowPath === ".github/workflows/ci.yml") {
+        ensureDir(".github/workflows");
+        (0, import_node_fs4.writeFileSync)(gcPath, renderGcWorkflowTemplate());
+      }
+    }
   }
   if (!dependencies.repoMutation || inputs.repoWriteMode === "none") {
     return { commitSha: "", resolvedCurrentRef: "", pushed: false };
   }
   const provisionPath = ".github/workflows/provision.yml";
-  const provisionExists = inputs.provider === "github" && (0, import_node_fs3.existsSync)(provisionPath);
+  const provisionExists = inputs.provider === "github" && (0, import_node_fs4.existsSync)(provisionPath);
+  const gcWorkflowPath = ".github/workflows/postman-preview-gc.yml";
+  const gcExists = inputs.generateCiWorkflow && (0, import_node_fs4.existsSync)(gcWorkflowPath);
   const stagePaths = [
     inputs.artifactDir,
     ".postman",
     inputs.generateCiWorkflow ? inputs.ciWorkflowPath : null,
+    gcExists ? gcWorkflowPath : null,
     provisionExists ? provisionPath : null
-  ].filter((entry) => typeof entry === "string" && ((0, import_node_fs3.existsSync)(entry) || entry === provisionPath));
+  ].filter((entry) => typeof entry === "string" && ((0, import_node_fs4.existsSync)(entry) || entry === provisionPath));
   if (stagePaths.length === 0) {
     dependencies.core.info("No generated repository paths were found; skipping repo mutation.");
     return {
@@ -129048,6 +129689,31 @@ async function runRepoSync(inputs, dependencies) {
   }
 }
 async function runRepoSyncInner(inputs, dependencies) {
+  const branchDecision = decideBranchTier(inputs);
+  assertBranchAssetIds(inputs, branchDecision);
+  const isCanonicalWriter = branchDecision.tier === "legacy" || branchDecision.tier === "canonical";
+  if (!isCanonicalWriter) {
+    if (branchDecision.tier === "preview" && branchDecision.identity.headBranch) {
+      inputs = {
+        ...inputs,
+        projectName: previewAssetName(inputs.projectName, branchDecision.identity.headBranch),
+        workspaceLinkEnabled: false,
+        environmentSyncEnabled: false,
+        repoWriteMode: "none"
+      };
+    } else if (branchDecision.tier === "channel" && branchDecision.channel) {
+      inputs = {
+        ...inputs,
+        projectName: channelAssetName(inputs.projectName, branchDecision.channel.code),
+        workspaceLinkEnabled: false,
+        environmentSyncEnabled: false,
+        repoWriteMode: "none"
+      };
+    }
+    dependencies.core.info(
+      `branch-aware sync: ${branchDecision.tier} run \u2014 branch-scoped asset set "${inputs.projectName}", no workspace repo-link mutation, no state write-back`
+    );
+  }
   const outputs = createOutputs(inputs);
   const versionRequested = inputs.collectionSyncMode === "version" || inputs.specSyncMode === "version";
   const releaseLabel = deriveReleaseLabel(inputs);
@@ -129055,7 +129721,8 @@ async function runRepoSyncInner(inputs, dependencies) {
     throw new Error("release-label is required when collection-sync-mode or spec-sync-mode is version");
   }
   const assetProjectName = createAssetProjectName(inputs, releaseLabel);
-  const resourcesState = readResourcesState();
+  const trackedState = readResourcesState();
+  const resourcesState = isCanonicalWriter ? trackedState : trackedState?.workspace ? { workspace: trackedState.workspace } : null;
   if (resourcesState) {
     if (!inputs.workspaceId && resourcesState.workspace?.id) {
       inputs.workspaceId = resourcesState.workspace.id;
@@ -129081,7 +129748,8 @@ async function runRepoSyncInner(inputs, dependencies) {
       }
     }
   }
-  const envUids = await upsertEnvironments(inputs, dependencies, resourcesState);
+  const branchAssetMarker = buildBranchAssetMarker(branchDecision, inputs);
+  const envUids = await upsertEnvironments(inputs, dependencies, resourcesState, branchAssetMarker);
   outputs["environment-uids-json"] = JSON.stringify(envUids);
   if (inputs.environmentSyncEnabled && inputs.workspaceId && dependencies.internalIntegration) {
     const associations = Object.entries(envUids).map(([envName, envUid]) => ({
@@ -129137,11 +129805,23 @@ async function runRepoSyncInner(inputs, dependencies) {
         }
       }
       if (!resolvedMockUrl) {
-        const mock = await dependencies.postman.createMock(
-          inputs.workspaceId,
-          mockName,
-          inputs.baselineCollectionId,
-          mockEnvUid
+        const mock = await retry(
+          () => dependencies.postman.createMock(
+            inputs.workspaceId,
+            mockName,
+            inputs.baselineCollectionId,
+            mockEnvUid
+          ),
+          {
+            maxAttempts: 3,
+            delayMs: 2e3,
+            backoffMultiplier: 2,
+            onRetry: ({ attempt, error: error2 }) => {
+              dependencies.core.warning(
+                `Mock create attempt ${attempt} failed (${error2 instanceof Error ? error2.message : String(error2)}); retrying`
+              );
+            }
+          }
         );
         resolvedMockUrl = mock.url;
         dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
@@ -129210,16 +129890,19 @@ async function runRepoSyncInner(inputs, dependencies) {
       );
     } catch (error2) {
       outputs["workspace-link-status"] = "failed";
-      dependencies.core.warning(
-        `Workspace link failed: ${error2 instanceof Error ? error2.message : String(error2)}`
-      );
+      const message = `Workspace link failed: ${error2 instanceof Error ? error2.message : String(error2)}`;
+      if (branchDecision.tier === "canonical") {
+        throw new Error(message, { cause: error2 });
+      }
+      dependencies.core.warning(message);
     }
   }
   await exportArtifacts(inputs, dependencies, envUids, assetProjectName, {
     workspaceLinkStatus: outputs["workspace-link-status"],
     priorWorkspaceId: resourcesState?.workspace?.id,
     existingSpecs: resourcesState?.cloudResources?.specs,
-    releaseLabel
+    releaseLabel,
+    priorState: resourcesState
   });
   const commit = await commitAndPushGeneratedFiles(inputs, dependencies);
   outputs["commit-sha"] = commit.commitSha;
@@ -129227,6 +129910,38 @@ async function runRepoSyncInner(inputs, dependencies) {
     outputs["resolved-current-ref"] = commit.resolvedCurrentRef;
   }
   outputs["repo-sync-summary-json"] = createRepoSummary(outputs, envUids, commit.pushed);
+  if (branchDecision.tier === "canonical" && inputs.specId && inputs.specContentChanged !== false && dependencies.postman.tagSpecVersion) {
+    const shortSha = (branchDecision.identity.headSha ?? "").slice(0, 7);
+    const tagName = inputs.releaseLabel ? `${inputs.releaseLabel}${shortSha ? ` (${shortSha})` : ""}` : shortSha || `sync-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
+    try {
+      const tag = await dependencies.postman.tagSpecVersion(inputs.specId, tagName);
+      outputs["spec-version-tag"] = tag.name || tagName;
+      if (tag.id) {
+        outputs["spec-version-url"] = `https://web.postman.co/workspace/${encodeURIComponent(inputs.workspaceId)}/specification/${encodeURIComponent(inputs.specId)}?tagId=${encodeURIComponent(tag.id)}&versionLabel=${encodeURIComponent(tag.name || tagName)}`;
+      }
+      dependencies.core.info(`Tagged spec version at finalize: ${tag.name || tagName}`);
+    } catch (error2) {
+      const status = error2.status;
+      if (status === 409) {
+        const tags = await dependencies.postman.listSpecVersionTags?.(inputs.specId).catch(() => []) ?? [];
+        const latest = tags[0];
+        if (latest && (latest.name === tagName || /\([0-9a-f]{7}\)$/.test(latest.name) || /^[0-9a-f]{7}$/.test(latest.name))) {
+          outputs["spec-version-tag"] = latest.name;
+          outputs["spec-version-url"] = `https://web.postman.co/workspace/${encodeURIComponent(inputs.workspaceId)}/specification/${encodeURIComponent(inputs.specId)}?tagId=${encodeURIComponent(latest.id)}&versionLabel=${encodeURIComponent(latest.name)}`;
+          dependencies.core.info(`Latest changelog group already tagged as "${latest.name}"; adopting.`);
+        } else {
+          dependencies.core.warning("Latest changelog group already carries a hand-applied tag; leaving it in place.");
+        }
+      } else {
+        dependencies.core.warning(`Spec version tagging failed (non-fatal): ${error2 instanceof Error ? error2.message : String(error2)}`);
+      }
+    }
+  }
+  if (inputs.branchStrategy !== "legacy" || process.env[BRANCH_DECISION_ENV]) {
+    const decision = decideBranchTier(inputs);
+    outputs["sync-status"] = "synced";
+    outputs["branch-decision"] = serializeBranchDecision(decision);
+  }
   for (const [name, value] of Object.entries(outputs)) {
     dependencies.core.setOutput(name, value);
   }
@@ -129416,7 +130131,19 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     listMonitors: gatewayAssets.listMonitors.bind(gatewayAssets),
     monitorExists: gatewayAssets.monitorExists.bind(gatewayAssets),
     findMonitorByCollection: gatewayAssets.findMonitorByCollection.bind(gatewayAssets),
-    runMonitor: gatewayAssets.runMonitor.bind(gatewayAssets)
+    runMonitor: gatewayAssets.runMonitor.bind(gatewayAssets),
+    listEnvironments: gatewayAssets.listEnvironments.bind(gatewayAssets),
+    // GC path (preview/channel retention machine — lib/repo/preview-gc.ts).
+    deleteEnvironment: gatewayAssets.deleteEnvironment.bind(gatewayAssets),
+    deleteMock: gatewayAssets.deleteMock.bind(gatewayAssets),
+    deleteMonitor: gatewayAssets.deleteMonitor.bind(gatewayAssets),
+    deleteCollection: gatewayAssets.deleteCollection.bind(gatewayAssets),
+    listSpecifications: gatewayAssets.listSpecifications.bind(gatewayAssets),
+    getSpecContent: gatewayAssets.getSpecContent.bind(gatewayAssets),
+    listSpecCollections: gatewayAssets.listSpecCollections.bind(gatewayAssets),
+    deleteSpec: gatewayAssets.deleteSpec.bind(gatewayAssets),
+    tagSpecVersion: gatewayAssets.tagSpecVersion.bind(gatewayAssets),
+    listSpecVersionTags: gatewayAssets.listSpecVersionTags.bind(gatewayAssets)
   };
   const repoMutation = repository && (inputs.repoWriteMode === "commit-only" || inputs.repoWriteMode === "commit-and-push") ? new RepoMutationService({
     provider: inputs.provider,
@@ -129453,8 +130180,43 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     repoMutation
   };
 }
+function decideBranchTier(inputs, env = process.env) {
+  return resolveEffectiveBranchDecision(
+    {
+      strategy: inputs.branchStrategy,
+      identity: resolveBranchIdentity(env, { defaultBranch: inputs.canonicalBranch }),
+      canonicalBranch: inputs.canonicalBranch,
+      channels: parseChannelRules(inputs.channels)
+    },
+    env
+  );
+}
+function runGatedSkip(inputs, decision, actionCore) {
+  actionCore.info(
+    `branch-aware sync: gated run (${decision.reason}) \u2014 repo-sync skipped, zero workspace writes`
+  );
+  const outputs = createOutputs(inputs);
+  outputs["sync-status"] = "skipped-branch-gate";
+  outputs["branch-decision"] = serializeBranchDecision(decision);
+  outputs["repo-sync-summary-json"] = JSON.stringify({
+    status: "skipped-branch-gate",
+    reason: decision.reason
+  });
+  for (const [name, value] of Object.entries(outputs)) {
+    actionCore.setOutput(name, value);
+  }
+  return outputs;
+}
 async function runAction(actionCore = core_exports, actionExec = exec_exports) {
   const inputs = readActionInputs(actionCore);
+  const branchDecision = decideBranchTier(inputs);
+  if (branchDecision.tier === "gated") {
+    return runGatedSkip(inputs, branchDecision, actionCore);
+  }
+  if (branchDecision.tier !== "legacy") {
+    actionCore.info(`branch-aware sync: tier=${branchDecision.tier} (${branchDecision.reason})`);
+    process.env[BRANCH_DECISION_ENV] = serializeBranchDecision(branchDecision);
+  }
   await mintAccessTokenIfNeeded(inputs, {
     info: (message) => actionCore.info(message),
     warning: (message) => actionCore.warning(message)