fix(release): 공개 대상 승인이 자리표시자 계약 신원을 거절한다 (U7 결정 2)

문제
- 기능 생성 명령(U7)은 계약 패키지 인자가 없으면 자리표시자 신원으로
  기능을 만든다. 이 신원은 형식 검사(external-contract-runtime.ts의
  패키지 신원 검사)를 모두 통과한다. 계약 집합 검사도 같은 목록을 자기
  자신과 비교한다. 그래서 자리표시자를 그대로 둔 빌드가 staging·
  production 승인까지 통과한다.

고른 방법 (오케스트레이터 결정 2)
- 자리표시자를 src/contracts/deployment-admission.ts에 상수로 둔다.
  digest는 sha256: 뒤에 0 64개, version 0.0.0, revision 0000000이다.
  생성 명령이 이 상수를 import해 쓰므로 코드에서 자리표시자임이 보인다.
- findAdmissionViolations에 세 번째 인자로 빌드가 컴파일한 계약 패키지
  목록을 받는다. 대상이 PUBLIC(staging, production)이면 digest가
  자리표시자인 패키지마다 contractPackages.<packageId> 위반을 낸다.
  BUILD_ID·RELEASE_ID의 PLACEHOLDER_IDENTIFIERS 검사와 같은 꼴이다.
- check-release-admission.ts는 EXPECTED_CONTRACT_SET_PACKAGES를 넘긴다.
  이미 COMPILED_PRODUCT_FEATURE_IDS를 같은 방식으로 읽는다.
- 배포된 config.json의 수정본 검사(--config, 1101/13-05)는 패키지를
  보지 않는다. 수정본은 비상 스위치만 바꿀 수 있고, 패키지는 빌드 필드라
  빌드 승인 때 이미 검사했다.
- APP_PROFILE 테스트의 production 행은 컴파일된 계약 집합에 자리표시자가
  있으면 거절(그 이유로만)을, 없으면 승인을 기대한다. 생성 명령으로
  기능을 하나 만들면 저장소 자체 빌드가 production 승인을 받지 못하는
  것이 의도한 동작이기 때문이다.
- 버린 대안: 계약 형식 검사에서 거절하기. 그러면 생성한 기능이 로컬에서
  부팅·테스트되지 않는다. dist/release-manifest.json을 읽어 비교하기.
  릴리스 일관성 검사가 이미 manifest와 컴파일된 목록이 같은지 보므로
  같은 값을 한 번 더 읽고, 이 스크립트를 실행하는 테스트마다 manifest를
  써야 한다.

위험·한계
- digest만 본다. version이나 revision만 자리표시자이고 digest는 진짜인
  신원은 거절하지 않는다. 결정이 digest 하나를 자리표시자로 정했다.
- local·development 대상은 거절하지 않는다. 의도한 동작이다.
- 새 코드는 앱 번들에 들어가지 않는다(빌드 후 dist에서 거절 문구와
  상수 이름 grep 0건). 앱은 이 모듈에서 isLoopbackHostname만 쓴다.

검증
- RED: 상수만 넣고 거절 전 코드로 새 테스트를 돌리면 실패한다.
  "staging: expected [] to deeply equal [ Array(1) ]"
- RED(수정본·APP_PROFILE): 생성 명령으로 기능 하나를 만든 상태에서
  두 테스트가 "contractPackages.@org-contracts/order: pins the
  placeholder identity ..."로 실패했다.
- GREEN: tests/unit/deployment-admission.test.ts 25/25,
  feature-override-diagnostics.test.ts(스크립트 실행) 통과. 생성한 기능이
  있을 때와 없을 때 모두 통과. 생성한 기능이 있을 때 production 대상
  스크립트 실행은 rc=1과 위 위반 한 줄을 낸다.
- npx tsc app·node·test rc=0, 바꾼 3파일 eslint rc=0.
This commit is contained in:
DongHyeonka
2026-11-03 06:52:43 +09:00
parent 64e98ee2fa
commit 1269992b1a
3 changed files with 87 additions and 4 deletions
+10 -1
View File
@@ -10,6 +10,7 @@ import {
} from "../src/contracts/deployment-admission.ts";
import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts";
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts";
import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts";
/**
@@ -136,7 +137,15 @@ async function main(): Promise<void> {
}
}
const violations = findAdmissionViolations(declared, config);
// U7 (decision 2). The packages the build compiled; a placeholder identity
// from create:feature is refused for staging and production. An edited copy
// is checked without them: packages are a build field it cannot change, and
// the build's own admission checked them.
const violations = findAdmissionViolations(
declared,
config,
editedCopy === undefined ? EXPECTED_CONTRACT_SET_PACKAGES : [],
);
// 09-09. Inert by design (a shared document may name another build's
// features), so this warns instead of refusing.
const warnings = unknownProductFeatureOverrides(
+30 -1
View File
@@ -45,6 +45,18 @@ const PLACEHOLDER_IDENTIFIERS: ReadonlySet<string> = new Set([
"unknown",
]);
/**
* U7 (decision 2). The contract package identity `pnpm create:feature` writes
* when no `--package` is given: an all-zero digest, version 0.0.0 and revision
* 0000000. It passes every format check (`external-contract-runtime.ts`), so a
* generated feature boots and tests locally; a public target refuses the
* digest below.
*/
export const PLACEHOLDER_CONTRACT_PACKAGE_DIGEST =
`sha256:${"0".repeat(64)}` as const;
export const PLACEHOLDER_CONTRACT_PACKAGE_VERSION = "0.0.0";
export const PLACEHOLDER_CONTRACT_PACKAGE_REVISION = "0000000";
export type AdmissionViolation = Readonly<{ field: string; reason: string }>;
export type AdmissionInput = RuntimeConfigArtifact &
@@ -57,13 +69,21 @@ export function isDeploymentTarget(value: unknown): value is DeploymentTarget {
);
}
/** The fields of a contract package identity admission reads. */
export type AdmissionContractPackage = Readonly<{
packageId: string;
digest: string;
}>;
/**
* Every reason this artifact may not be deployed to `target`. An empty list is
* the only admission.
* the only admission. `contractPackages` is the contract set the build
* compiled (`EXPECTED_CONTRACT_SET_PACKAGES`).
*/
export function findAdmissionViolations(
target: DeploymentTarget,
config: AdmissionInput,
contractPackages: readonly AdmissionContractPackage[] = [],
): readonly AdmissionViolation[] {
const violations: AdmissionViolation[] = [];
if (config.APP_ENV !== target) {
@@ -105,6 +125,15 @@ export function findAdmissionViolations(
});
}
}
for (const contractPackage of contractPackages) {
if (contractPackage.digest === PLACEHOLDER_CONTRACT_PACKAGE_DIGEST) {
violations.push({
field: `contractPackages.${contractPackage.packageId}`,
reason:
"pins the placeholder identity create:feature writes; pin the published package's version, digest and revision",
});
}
}
return Object.freeze(violations);
}
+47 -2
View File
@@ -9,9 +9,11 @@ import {
DEPLOYMENT_TARGETS,
findAdmissionViolations,
isDeploymentTarget,
PLACEHOLDER_CONTRACT_PACKAGE_DIGEST,
type AdmissionInput,
} from "../../src/contracts/deployment-admission.ts";
import { ENV_REGISTRY, getBuildConfig } from "../../src/contracts/env.ts";
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../../src/features/installed-contract-contributions.ts";
import { runtimeConfigV2ArtifactSchema } from "../../src/contracts/release-artifacts.ts";
import { generateRuntimeConfig } from "../../scripts/generate-runtime-config.ts";
@@ -49,6 +51,39 @@ describe("deployment admission", () => {
expect(findAdmissionViolations("local", LOCAL_ARTIFACT)).toEqual([]);
});
// U7 (decision 2). `create:feature` pins this digest when no contract
// package is given. It passes every format check, so a public target is
// where it stops; local and development builds keep working with it.
it("refuses a contract package that pins the placeholder digest for a public target", () => {
const placeholder = Object.freeze({
packageId: "@org-contracts/orders",
digest: PLACEHOLDER_CONTRACT_PACKAGE_DIGEST,
});
const published = Object.freeze({
packageId: "@org-contracts/billing",
digest: `sha256:${"a".repeat(64)}` as const,
});
expect(PLACEHOLDER_CONTRACT_PACKAGE_DIGEST).toBe(`sha256:${"0".repeat(64)}`);
for (const target of ["staging", "production"] as const) {
expect(
findAdmissionViolations(
target,
{ ...PRODUCTION_ARTIFACT, APP_ENV: target },
[placeholder, published],
).map((violation) => violation.field),
target,
).toEqual(["contractPackages.@org-contracts/orders"]);
}
for (const target of ["local", "development"] as const) {
expect(
findAdmissionViolations(target, { ...LOCAL_ARTIFACT, APP_ENV: target }, [
placeholder,
]),
target,
).toEqual([]);
}
});
it("refuses the exact local build that release coherence used to approve", () => {
// The review's strongest reproduction: FE-GATE-015 passed on a build whose
// runtime document was APP_ENV=local / AUTH_MODE=demo / loopback API. Each
@@ -289,9 +324,15 @@ describe("runtime config profiles", () => {
// 13-01: the build profile and the admission target are two repository
// variables. A staging profile left in place for a production release has to
// stop the release, whatever the built document happens to say.
// U7 (decision 2): the script also refuses the compiled contract set while a
// feature from create:feature still pins the placeholder package, so with
// one installed the matching profile is refused for that reason only.
const placeholderInstalled = EXPECTED_CONTRACT_SET_PACKAGES.some(
({ digest }) => digest === PLACEHOLDER_CONTRACT_PACKAGE_DIGEST,
);
it.each([
["staging", 1],
["production", 0],
["production", placeholderInstalled ? 1 : 0],
] as const)("admits a production artifact under APP_PROFILE=%s only when it names the target", async (profile, status) => {
const root = await mkdtemp(path.join(tmpdir(), "release-admission-profile-"));
try {
@@ -308,7 +349,11 @@ describe("runtime config profiles", () => {
},
);
expect(result.status, result.stderr).toBe(status);
if (status === 1) expect(result.stderr).toMatch(/APP_PROFILE=staging/u);
if (profile === "staging") {
expect(result.stderr).toMatch(/APP_PROFILE=staging/u);
} else {
expect(result.stderr).not.toMatch(/APP_PROFILE/u);
}
} finally {
await rm(root, { recursive: true, force: true });
}