canopycms 0.7.1 → 0.8.0

package/dist/submission-attribution.d.ts

@@ -1,6 +1,7 @@
 import type { UserSearchResult } from './auth/types.js';
 import type { CanopyUser } from './user.js';
 import type { CommentThread } from './comment-store.js';
+import type { BranchReview } from './types.js';
 /**
  * Who submitted (and edited) a branch, recorded in the submit commit's trailers
  * and the pull request body. The bot stays the commit author; these records are
@@ -33,6 +34,14 @@ export declare const PR_SECTION_END = "<!-- canopycms:submission:end -->";
 export declare const PR_COMMENTS_START = "<!-- canopycms:comments:start -->";
 /** @internal Exported for tests. */
 export declare const PR_COMMENTS_END = "<!-- canopycms:comments:end -->";
+/**
+ * The reviewer's verdict, nested in the section like the comment block so a review action can
+ * replace it alone (mergeReviewBlock).
+ * @internal Exported for tests.
+ */
+export declare const PR_REVIEW_START = "<!-- canopycms:review:start -->";
+/** @internal Exported for tests. */
+export declare const PR_REVIEW_END = "<!-- canopycms:review:end -->";
 /**
  * A display name safe for a single line of git trailer or Markdown, or undefined.
  * @internal Exported for tests.
@@ -87,6 +96,12 @@ export interface PrSectionInput {
     /** The branch's editor comment threads (comments.json), or null when they could not be read. */
     threads?: readonly CommentThread[] | null;
 }
+/**
+ * The reviewer's verdict between its markers. The name is a cleaned code span, so it cannot
+ * mention, reference an issue, carry HTML or spell a marker; the id is never written, and a
+ * name that is only the id counts as none.
+ */
+export declare function buildReviewBlock(review: BranchReview | undefined): string;
 /**
  * The editor-comment summary between its markers: the unresolved threads, oldest first, or
  * that every thread is resolved, or that there are none, or that they could not be read.
@@ -116,3 +131,10 @@ export declare function mergePrSection(existing: string | null | undefined, sect
  * count, and the description in it cannot spell one (neutralizeComments).
  */
 export declare function mergeCommentsBlock(existing: string | null | undefined, block: string): string | undefined;
+/**
+ * `existing` with the review block inside its canopycms section replaced by `block`, or
+ * undefined when the section or its block is missing (a PR body written before the block
+ * existed, or edited by hand): the next submit writes it. Markers are found as in
+ * mergeCommentsBlock.
+ */
+export declare function mergeReviewBlock(existing: string | null | undefined, block: string): string | undefined;

package/dist/submission-attribution.js

@@ -29,6 +29,14 @@ export const PR_SECTION_END = '<!-- canopycms:submission:end -->';
 export const PR_COMMENTS_START = '<!-- canopycms:comments:start -->';
 /** @internal Exported for tests. */
 export const PR_COMMENTS_END = '<!-- canopycms:comments:end -->';
+/**
+ * The reviewer's verdict, nested in the section like the comment block so a review action can
+ * replace it alone (mergeReviewBlock).
+ * @internal Exported for tests.
+ */
+export const PR_REVIEW_START = '<!-- canopycms:review:start -->';
+/** @internal Exported for tests. */
+export const PR_REVIEW_END = '<!-- canopycms:review:end -->';
 // Cc (C0/C1 controls incl. newlines), Cf (zero-width and bidi overrides), Zl/Zp
 // (Unicode line/paragraph separators) can forge a trailer line or hide text; Cs
 // (a lone surrogate) reaches git as U+FFFD, since Node encodes it so.
@@ -222,6 +230,34 @@ function editorLabel(editor) {
 function editorLinker(branch, editorUrl) {
     return (entryPath) => branch && editorUrl ? markdownHref(editorDeepLink(editorUrl, branch, entryPath)) : undefined;
 }
+const REVIEW_NOT_A_GITHUB_REVIEW = 'Approval in CanopyCMS is not a GitHub review.';
+/** The UTC minute as `date time UTC`, or undefined for a timestamp that is not a date. */
+function reviewTime(at) {
+    const time = typeof at === 'string' ? new Date(at) : undefined;
+    return time && !Number.isNaN(time.getTime())
+        ? `${time.toISOString().slice(0, 16).replace('T', ' ')} UTC`
+        : undefined;
+}
+/**
+ * The reviewer's verdict between its markers. The name is a cleaned code span, so it cannot
+ * mention, reference an issue, carry HTML or spell a marker; the id is never written, and a
+ * name that is only the id counts as none.
+ */
+export function buildReviewBlock(review) {
+    const verdict = review?.state === 'approved'
+        ? 'Approved'
+        : review?.state === 'changes-requested'
+            ? 'Changes requested'
+            : undefined;
+    let status = 'Not yet reviewed in CanopyCMS.';
+    if (review && verdict) {
+        // Cleaned first, so a name that becomes the id once cleaned still counts as none.
+        const name = personName(review.by.userId, sanitizeDisplayName(review.by.name));
+        const when = reviewTime(review.at);
+        status = `${verdict} in CanopyCMS by ${name ? codeSpan(name) : 'a reviewer'}${when ? ` on ${when}` : ''}.`;
+    }
+    return `${PR_REVIEW_START}\n${status}\n${REVIEW_NOT_A_GITHUB_REVIEW}\n${PR_REVIEW_END}`;
+}
 const MAX_LISTED_THREADS = 50;
 const MAX_EXCERPT_LENGTH = 80;
 const MAX_COMMENTS_LENGTH = 15_000;
@@ -296,7 +332,7 @@ export function buildCommentsBlock(threads, branch, editorUrl) {
     }
     return `${PR_COMMENTS_START}\n${body}\n${PR_COMMENTS_END}`;
 }
-function renderPrSection(input, layout, commentsBlock) {
+function renderPrSection(input, layout, commentsBlock, reviewBlock) {
     const parts = [];
     const [submitter] = input.submitter ? cleanEditors([input.submitter]) : [];
     parts.push(submitter
@@ -306,6 +342,7 @@ function renderPrSection(input, layout, commentsBlock) {
     if (others.length > 0) {
         parts.push(`Also edited by: ${others.map(editorLabel).join(', ')}`);
     }
+    parts.push(reviewBlock);
     const link = editorLinker(input.branch, input.editorUrl);
     const branchLink = link();
     if (branchLink)
@@ -359,23 +396,25 @@ export function buildPrSection(input) {
     const raw = input.description?.trim();
     const description = raw ? neutralizeComments(truncate(raw, MAX_DESCRIPTION_LENGTH)) : '';
     const block = buildCommentsBlock(input.threads === undefined ? [] : input.threads, input.branch, input.editorUrl);
-    const size = (l) => renderPrSection(input, l, block).length - block.length;
+    // A submit clears the stored review, so a new section starts unreviewed.
+    const reviewBlock = buildReviewBlock(undefined);
+    const size = (l) => renderPrSection(input, l, block, reviewBlock).length - block.length;
     const layout = { entryLinks: true, listed: MAX_LISTED_ENTRIES, description };
     const fits = (l) => size(l) <= MAX_SECTION_LENGTH;
     if (fits(layout))
-        return renderPrSection(input, layout, block);
+        return renderPrSection(input, layout, block, reviewBlock);
     layout.entryLinks = false;
     if (fits(layout))
-        return renderPrSection(input, layout, block);
+        return renderPrSection(input, layout, block, reviewBlock);
     // The description's separator is two newlines.
     const room = MAX_SECTION_LENGTH - size({ ...layout, description: '' }) - 2;
     if (room > 0) {
-        return renderPrSection(input, { ...layout, description: truncateUnits(description, room) }, block);
+        return renderPrSection(input, { ...layout, description: truncateUnits(description, room) }, block, reviewBlock);
     }
     layout.description = '';
     while (layout.listed > 0 && !fits(layout))
         layout.listed = Math.max(0, layout.listed - 10);
-    return renderPrSection(input, layout, block);
+    return renderPrSection(input, layout, block, reviewBlock);
 }
 /**
  * `existing` with its canopycms section replaced by `section`, keeping every
@@ -420,3 +459,20 @@ export function mergeCommentsBlock(existing, block) {
         return undefined;
     return body.slice(0, start) + block + body.slice(end + PR_COMMENTS_END.length);
 }
+/**
+ * `existing` with the review block inside its canopycms section replaced by `block`, or
+ * undefined when the section or its block is missing (a PR body written before the block
+ * existed, or edited by hand): the next submit writes it. Markers are found as in
+ * mergeCommentsBlock.
+ */
+export function mergeReviewBlock(existing, block) {
+    const body = existing ?? '';
+    const section = findPrSection(body);
+    if (!section)
+        return undefined;
+    const start = body.indexOf(PR_REVIEW_START, section.start);
+    const end = start < 0 ? -1 : body.indexOf(PR_REVIEW_END, start);
+    if (start < 0 || end < 0 || end > section.end)
+        return undefined;
+    return body.slice(0, start) + block + body.slice(end + PR_REVIEW_END.length);
+}

package/dist/task-queue/worker-status.d.ts

@@ -2,7 +2,7 @@
  * worker-status.json: the CmsWorker daemon's self-reported liveness/health
  * snapshot, written under the task queue directory
  * (`{taskDir}/worker-status.json`) and read tolerantly by the admin API
- * (api/admin.ts's `readWorkerStatus`). Wire shape: `WorkerStatusReport` in
+ * (`readWorkerStatus`). Wire shape: `WorkerStatusReport` in
  * ../types.
  *
  * Single-writer by intent (only the lock-holding CmsWorker -- see
@@ -21,6 +21,11 @@
  */
 import type { WorkerStatusReport } from '../types.js';
 export declare const WORKER_STATUS_FILE = "worker-status.json";
+/** The status file as last written, null when there is none, and why it could not be read. */
+export declare function readWorkerStatus(taskDir: string): Promise<{
+    workerStatus: WorkerStatusReport | null;
+    statusReadError?: string;
+}>;
 /**
  * What a new worker carries from the previous status file into its first snapshot:
  * `lastFatalError`, so a crash loop keeps its alert, and how the last worker that ran stopped.

package/dist/task-queue/worker-status.js

@@ -2,7 +2,7 @@
  * worker-status.json: the CmsWorker daemon's self-reported liveness/health
  * snapshot, written under the task queue directory
  * (`{taskDir}/worker-status.json`) and read tolerantly by the admin API
- * (api/admin.ts's `readWorkerStatus`). Wire shape: `WorkerStatusReport` in
+ * (`readWorkerStatus`). Wire shape: `WorkerStatusReport` in
  * ../types.
  *
  * Single-writer by intent (only the lock-holding CmsWorker -- see
@@ -22,8 +22,29 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { atomicWriteFile } from '../utils/atomic-write.js';
-import { isNotFoundError } from '../utils/error.js';
+import { getErrorMessage, isNotFoundError } from '../utils/error.js';
 export const WORKER_STATUS_FILE = 'worker-status.json';
+/** The status file as last written, null when there is none, and why it could not be read. */
+export async function readWorkerStatus(taskDir) {
+    let content;
+    try {
+        content = await fs.readFile(path.join(taskDir, WORKER_STATUS_FILE), 'utf-8');
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return { workerStatus: null };
+        return { workerStatus: null, statusReadError: getErrorMessage(err) };
+    }
+    try {
+        // Cast, not validated. The CMS Lambda can write this file too, since it mounts the same EFS,
+        // but every caller of this reader runs in the Lambda, so a forged file misleads only the
+        // Lambda itself and the System health it serves.
+        return { workerStatus: JSON.parse(content) };
+    }
+    catch (err) {
+        return { workerStatus: null, statusReadError: getErrorMessage(err) };
+    }
+}
 /**
  * What a new worker carries from the previous status file into its first snapshot:
  * `lastFatalError`, so a crash loop keeps its alert, and how the last worker that ran stopped.

package/dist/types.d.ts

@@ -20,6 +20,20 @@ export interface BranchAccessControl {
     allowedGroups?: CanopyGroupId[];
     managerOrAdminAllowed?: boolean;
 }
+/**
+ * A reviewer's verdict on the branch as last submitted, shown in the pull request body
+ * (submission-attribution.ts). Set by approve and request-changes, cleared by submit and
+ * withdraw, and never sent to clients: `by` names the reviewer.
+ */
+export interface BranchReview {
+    state: 'approved' | 'changes-requested';
+    by: {
+        userId: CanopyUserId;
+        name?: string;
+    };
+    /** ISO timestamp of the verdict. */
+    at: string;
+}
 export interface BranchMetadata {
     name: string;
     title?: string;
@@ -111,6 +125,8 @@ export interface BranchMetadata {
     editors?: CanopyUserId[];
     /** The `editors` who saved since the last submit commit; the next one's trailers name them. */
     uncommittedEditors?: CanopyUserId[];
+    /** The reviewer's verdict on the last submit; absent until a reviewer acts. */
+    review?: BranchReview;
 }
 export interface BranchPaths {
     /** Root where all branches live (e.g., /mnt/efs/site, ~/.canopycms/branches) */
@@ -175,6 +191,33 @@ export interface BaseSchemaHold {
     /** Set on the cycle the hold outlived its bound and the worker advanced anyway. */
     expired?: true;
 }
+/**
+ * Why listing an unpublishable branch in `legacyBranches` would not publish it.
+ * `blocks-namespace`: it is named after part of the namespace, so while it exists neither
+ * remote.git nor GitHub holds a branch in the namespace. `unlistable`: `legacyBranches` refuses
+ * its name. The report lists branch workspaces only, read from their branch.json: a blocker that
+ * exists only on GitHub is never listed, even after `reconcileTrackedBranches` brings it into
+ * remote.git.
+ */
+export type UnpublishableBranchReason = 'blocks-namespace' | 'unlistable';
+/** A branch the GitHub gateway will not publish, by ref. */
+export interface UnpublishableBranch {
+    name: string;
+    /**
+     * Absent when neither applies: a `legacyBranches` entry would then publish it unless it is
+     * protected, by `protectedBranches`, as the base branch, or as GitHub's default branch.
+     */
+    reason?: UnpublishableBranchReason;
+}
+/**
+ * Branches the GitHub gateway will not publish: at most 50 `branches`, of `count` in all, as of
+ * `at` (ISO).
+ */
+export interface UnpublishableBranchesReport {
+    branches: UnpublishableBranch[];
+    count: number;
+    at: string;
+}
 /**
  * Wire shape of the worker's self-reported status file (worker-status.json, under
  * the task queue dir), written by the CmsWorker daemon. Read-only here: GET
@@ -248,6 +291,22 @@ export interface WorkerStatusReport {
          */
         workerStartedAt?: string;
     };
+    /**
+     * The branch namespace the GitHub gateway writes, as of the last git sync that could ask it.
+     * System health compares it with the namespace the CMS creates branches in.
+     */
+    gatewayBranchNamespace?: string;
+    /**
+     * The exact names the GitHub gateway protects, its base branch among them, as of the same sync.
+     * Branch creation refuses a short name equal to one.
+     */
+    gatewayProtectedBranches?: string[];
+    /**
+     * Editor branches the GitHub gateway will not publish, as of the last git sync that could ask
+     * it; absent when there are none (worker/unpublishable-branches.ts). Carried into a restarted
+     * worker's first snapshot.
+     */
+    unpublishableBranches?: UnpublishableBranchesReport;
     /**
      * Present while the schema gate holds the base branch, and on the cycle a hold expires. Carried
      * into a restarted worker's first snapshot, so the bound survives restarts.

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CANOPYCMS_VERSION = "0.7.1";
+export declare const CANOPYCMS_VERSION = "0.8.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
 // tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
-export const CANOPYCMS_VERSION = '0.7.1';
+export const CANOPYCMS_VERSION = '0.8.0';

package/dist/worker/branch-policy.d.ts

@@ -16,7 +16,9 @@ export declare const MAX_PULL_REQUEST_TITLE_LENGTH = 1024;
  */
 export declare const MAX_PULL_REQUEST_BODY_LENGTH = 65536;
 export type GatewayOperation = 'push' | 'delete' | 'pull-request';
-export type RefusalReason = 'invalid' | 'protected' | 'settings' | 'not-a-commit' | 'too-long';
+export type RefusalReason = 'invalid' | 'protected' | 'settings' | 'other-settings' | 'outside-namespace' | 'not-a-commit' | 'too-long';
+/** The refusals {@link BranchPolicy.assertPushAllowed} makes. */
+export type PushPolicyRefusal = 'protected' | 'settings' | 'other-settings' | 'outside-namespace';
 /**
  * Something the gateway refuses to do for any caller. No CanopyCMS flow asks for it, so no retry
  * can change the answer: the task runner fails such a task permanently, and a refusal never arms
@@ -28,6 +30,15 @@ export declare class GatewayRefusalError extends Error {
     readonly reason: RefusalReason;
     constructor(operation: GatewayOperation, branch: string, reason: RefusalReason, message: string);
 }
+/**
+ * Why the policy refuses to push `branch`, for `reason`, in `namespace`.
+ * @internal Exported for tests.
+ */
+export declare function pushRefusalMessage(branch: string, reason: PushPolicyRefusal, namespace: string): string;
+/** Why the gateway refuses to push `branch`, in the namespace, while GitHub has `blocker`. */
+export declare function namespaceBlockedMessage(branch: string, blocker: string): string;
+/** Why a push of `branch` is refused while GitHub has `inside`, a branch inside it. */
+export declare function branchInsideMessage(branch: string, inside: string): string;
 /**
  * Why `branch` is not a name the gateway takes, before git sees it, or null. Printable ASCII only,
  * so no two names differ invisibly; no `"`, `%`, `{` or `}`, which reach URLs and log lines; no
@@ -44,6 +55,15 @@ export declare function branchNameProblem(branch: string): string | null;
  * @internal Exported for tests.
  */
 export declare function protectedPatternProblem(pattern: string): string | null;
+/**
+ * Why `entry` cannot be a `legacyBranches` entry, whatever the namespace, or null. An entry is an
+ * exact branch name git can push: a `*` would admit names no one listed, and one alone would
+ * switch the namespace off. A comma separates entries in `CANOPYCMS_LEGACY_BRANCHES`. The CDK's
+ * `assertValidLegacyBranches` holds a copy of these rules and the constructor's, both held to
+ * worker/legacy-branch-fixtures.ts.
+ * @internal Exported for tests.
+ */
+export declare function legacyBranchProblem(entry: string): string | null;
 /**
  * Whether `name` matches `pattern`, where `*` matches any run of characters. Never a regex.
  * @internal Exported for tests.
@@ -54,18 +74,51 @@ export declare function matchesBranchPattern(pattern: string, name: string): boo
  * branch (`describe()`), so its bound is one above this.
  */
 export declare const MAX_PROTECTED_BRANCHES = 1024;
+/** The most `legacyBranches` entries a policy takes. */
+export declare const MAX_LEGACY_BRANCHES = 1024;
+/**
+ * The namespace a policy enforces when it is given none: the default template's, for the default
+ * deployment name.
+ * @internal Exported for tests.
+ */
+export declare const DEFAULT_BRANCH_NAMESPACE: string;
 export interface BranchPolicyOptions {
+    /**
+     * The namespace this gateway writes (`CANOPYCMS_BRANCH_NAMESPACE` resolved,
+     * operating-mode/branch-namespace.ts). Default {@link DEFAULT_BRANCH_NAMESPACE}.
+     */
+    namespace?: string;
     /** The configured base branch (`CANOPYCMS_BASE_BRANCH`); never one read from the workspace. */
     baseBranch?: string;
     /** Further protected names and `*` globs (`CANOPYCMS_PROTECTED_BRANCHES`). */
     protectedBranches?: readonly string[];
+    /**
+     * This deployment's settings branch, the only one pushed. Without it no settings branch is.
+     */
+    settingsBranch?: string;
+    /**
+     * Branches outside the namespace that may still be written: exact names, from before the
+     * namespace (`CANOPYCMS_LEGACY_BRANCHES`).
+     */
+    legacyBranches?: readonly string[];
     /** Test seam: the clock {@link DEFAULT_BRANCH_TTL_MS} is measured on. */
     now?: () => number;
 }
+/** What {@link BranchPolicy.describe} answers, which the gateway's health carries. */
+export interface BranchPolicyDescription {
+    /** The protected set's configured names and globs, the base branch included. */
+    configured: string[];
+    /** GitHub's default branch as last read; null before a read or for a repository with none. */
+    githubDefault: string | null;
+    /** The namespace the gateway writes. */
+    namespace: string;
+    legacy: string[];
+    settingsBranch: string | null;
+}
 /** Reads GitHub's default branch: null for a repository with none. */
 export type DefaultBranchReader = () => Promise<string | null>;
 /**
- * The protected set and the settings rules.
+ * The protected set, the namespace and the settings rules.
  *
  * A branch is protected when it is the configured base branch, GitHub's default branch or a
  * `protectedBranches` entry, compared case-sensitively as GitHub compares refs. An exact entry
@@ -76,38 +129,74 @@ export type DefaultBranchReader = () => Promise<string | null>;
  * Reads are not shared between concurrent callers, because a push reads inside a mirror session
  * and an operation that joined it from outside one would wait on that session.
  *
+ * Nothing outside the namespace is written: a push, deletion or pull request head must start with
+ * the namespace, be this deployment's settings branch, or be a `legacyBranches` entry, compared
+ * exactly. Sanitized equivalence, right for the protected set where matching more refuses more,
+ * would let an allow-list admit more. The protected set wins inside the namespace too. The
+ * namespace comes from the gateway's own configuration, never a request. The base and settings
+ * branches must lie outside it, by name and by workspace directory, and not be named after part of
+ * it, since git then holds no branch in it; a legacy entry inside it is refused as pointless, and
+ * one named after part of it as blocking it.
+ *
  * Settings branches are pushed plainly or not at all: no lease, no deletion, no pull request.
- * One is a name with the reserved prefix, the task runner's own test (`isSettingsBranch`): branch
- * creation refuses the prefix, while a configured settings name without it could be a content
- * branch's.
+ * One is a name with the reserved prefix or this deployment's settings branch. Only this
+ * deployment's is pushed: another deployment sharing the repository owns its own.
  */
 export declare class BranchPolicy {
     private readonly exact;
     private readonly globs;
+    /** The namespace the gateway writes. */
+    readonly namespace: string;
+    private readonly settingsBranch;
+    private readonly legacy;
     private readonly now;
     private githubDefault;
     constructor(options?: BranchPolicyOptions);
-    /** The protected set as it stands: configured names and globs, and GitHub's default as last read. */
-    describe(): {
-        configured: string[];
-        githubDefault: string | null;
-    };
+    /** The policy as it stands. */
+    describe(): BranchPolicyDescription;
+    /** Whether the gateway may write `branch` at all: the namespace, the settings branch, the list. */
+    inNamespace(branch: string): boolean;
+    /**
+     * Whether the gateway opens and updates a pull request from `head`, protection aside: a branch it
+     * writes that is not a settings branch. `isProtected`, which may read GitHub, judges the rest.
+     */
+    takesPullRequestFrom(head: string): boolean;
+    /**
+     * The branch among `branches` named after part of the namespace, or null. While one exists git
+     * holds no branch in the namespace, so the gateway refuses a push into it rather than send it.
+     */
+    namespaceBlocker(branches: {
+        has(name: string): boolean;
+    }): string | null;
     /** Whether `branch` is protected; GitHub's default is read only when nothing else matches. */
     isProtected(branch: string, readDefault: DefaultBranchReader): Promise<boolean>;
-    /** Refuse a push to a protected branch, or a leased push to a settings branch. */
-    assertPushAllowed(branch: string, lease: string | undefined, readDefault: DefaultBranchReader, refuse: (reason: 'protected' | 'settings') => Error): Promise<void>;
-    /** Refuse to delete a protected branch or a settings branch. */
+    /**
+     * Whether `branch` is GitHub's default branch as last read, even once that read has expired:
+     * what protection is judged by when a fresh read fails.
+     */
+    matchesLastReadDefault(branch: string): boolean;
+    /**
+     * Refuse a push to a protected branch, a leased push to a settings branch, a push to another
+     * deployment's settings branch, and a push outside the namespace.
+     */
+    assertPushAllowed(branch: string, lease: string | undefined, readDefault: DefaultBranchReader, refuse: (reason: PushPolicyRefusal, message: string) => Error): Promise<void>;
+    /** Refuse to delete a protected branch, a settings branch, or one outside the namespace. */
     assertDeleteAllowed(branch: string, readDefault: DefaultBranchReader): Promise<void>;
     /**
-     * Refuse a pull request whose head is protected or a settings branch, or whose text is over its
-     * cap. The base is not restricted: a branch keeps the base it was created from after the
-     * adopter moves theirs, and a pull request merges nothing by itself.
+     * Refuse a pull request whose head is protected, a settings branch or outside the namespace, or
+     * whose text is over its cap. The base is not restricted: a branch keeps the base it was created
+     * from after the adopter moves theirs, and a pull request merges nothing by itself.
      */
     assertPullRequestAllowed(request: {
         head: string;
         title?: string;
         body?: string;
     }, readDefault: DefaultBranchReader): Promise<void>;
+    /**
+     * Refuse a pull request head the gateway may not open one from, or act on one with. `refusing`
+     * opens the message and names `head`, which the rest calls "it".
+     */
+    assertPullRequestHeadAllowed(refusing: string, head: string, readDefault: DefaultBranchReader): Promise<void>;
     private isSettings;
     private matchesConfigured;
     private githubDefaultBranch;
@@ -117,6 +206,12 @@ export declare class BranchPolicy {
      */
     recordGitHubDefault(readDefault: DefaultBranchReader): Promise<string | null>;
 }
+/**
+ * Whether the gateway that described its policy as `policy` would take a plain push of `branch`:
+ * `BranchPolicy.assertPushAllowed`'s rules, for a reader that has only the description, with
+ * GitHub's default as last read. A test holds the two equal.
+ */
+export declare function publishesBranch(policy: BranchPolicyDescription, branch: string): boolean;
 /** Refuse pull request text over its cap; `refusing` opens the message, `branch` names its head. */
 export declare function assertPullRequestText(refusing: string, branch: string, text: {
     title?: string;