ai-saas-guard 0.14.0 → 0.16.0

package/README.md

@@ -73,8 +73,8 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
-| Versioned Action tags | `v0.14.0`, `v0` |
-| npm package | `ai-saas-guard@0.14.0` |
+| Versioned Action tags | `v0.16.0`, `v0` |
+| npm package | `ai-saas-guard@0.16.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -208,19 +208,19 @@ The first hosted service slice is defined in [docs/hosted-first-service-slice.md
 
 The hosted deployment model is documented in [docs/hosted-deployment-model.md](docs/hosted-deployment-model.md). It chooses a containerized Node.js ingress and worker model with a managed durable queue, platform secret manager, structured redacted logs, installation/repository rate limits, and rollback/incident response paths.
 
-The hosted operational release gate is documented in [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md). It defines the hosted-specific CI, replay, queue, worker cleanup, privacy, monitoring, rollback, and incident-response evidence required before any hosted environment is exposed to users.
+The hosted operational release gate is documented in [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md). It defines the hosted-specific CI, replay, queue, worker cleanup, privacy, monitoring, rollback, and incident-response evidence required before any hosted environment is exposed to users. The pure gate evaluator exported from `ai-saas-guard/hosted/contracts` blocks hosted exposure unless every P0 evidence item is fresh, a container digest is recorded, and release notes avoid pentest, certification, and full-audit claims.
 
 Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninstall-data-deletion.md](docs/hosted-uninstall-data-deletion.md). It defines repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup, and user-facing deletion wording.
 
 Hosted pricing and packaging boundaries are documented in [docs/hosted-pricing-packaging.md](docs/hosted-pricing-packaging.md). Core local scanning stays useful without an account; hosted plans may add workflow convenience, saved reports, team policy, and optional human review, but they do not gate local CLI scanning.
 
-Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key, a worker read-only scan planner that fixes the CLI command and requires repository `contents: read`, and a Check Run publication planner that requires repository `checks: write` and builds bounded check-only payloads from compact reports. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, and other service-free helpers exported from `ai-saas-guard/hosted/contracts`. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
+Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key, a worker read-only scan planner that fixes the CLI command and requires repository `contents: read`, and a Check Run publication planner that requires repository `checks: write` and builds bounded check-only payloads from compact reports. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, a retention/deletion cleanup planner, and an operational release gate evaluator that requires fresh CI, replay, static-check, dependency, container, cleanup, privacy, monitoring, rollback, incident-response, and release-cleanup evidence before hosted exposure. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
 
 A public hosted compact report schema fixture is available at [examples/hosted-compact-report.json](examples/hosted-compact-report.json). It is synthetic and public-safe: compact evidence only, no raw source, raw diffs, secrets, webhook payload bodies, customer payloads, private URLs, or worker checkout paths.
 
 The proposed hosted app permission boundary is intentionally narrow: repository contents read, pull requests read, checks write, and metadata read for the first version. Optional PR comments require repository policy opt-in, and broad permissions such as administration, deployments, Actions write, and repository secrets are out of scope.
 
-The repository also includes pure pre-implementation hosted contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, and retention limits. These helpers do not implement or deploy a hosted service.
+The repository also includes pure pre-implementation hosted contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, and operational release gate blocking. These helpers do not implement or deploy a hosted service.
 
 Users should prefer the local CLI for private repositories, offline review, or no-account workflows where hosted code processing is not acceptable.
 
@@ -254,7 +254,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.14.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.16.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/README.zh-CN.md

@@ -55,7 +55,7 @@ AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.14.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.14.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.16.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.16.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,8 +66,8 @@ CLI 已发布到 npm：`ai-saas-guard@0.14.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.14.0` |
-| Action 标签 | `v0.14.0`、`v0` |
+| 当前版本 | `0.16.0` |
+| Action 标签 | `v0.16.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 
 ## 快速开始
@@ -260,6 +260,8 @@ jobs:
 - Check Run publication planner：要求 repository `checks: write`，只从 compact report 生成有长度上限的 Check Run payload，包含 review categories、优先 review 文件、verification steps 和本地 CLI 复现命令；MVP 不发 PR comment
 - queue cleanup planner
 - worker checkout cleanup planner
+- retention/deletion cleanup planner：把 compact report 删除、按仓库或 installation 范围取消队列和 running job、worker checkout 删除、retention 过期清理、最小审计记录合成一个安全计划；不会输出源码、diff、secret、customer payload、private URL、checkout path 或底层 cleanup error
+- operational release gate evaluator：检查 hosted 暴露前是否具备 fresh CI、webhook replay、workflow static check、dependency/container scan、cleanup、privacy、monitoring、rollback、incident response 和 release cleanup 证据；缺任何 P0 证据都会阻止 hosted exposure
 - hosted compact report fixture：[examples/hosted-compact-report.json](examples/hosted-compact-report.json)
 
 这些 helper 不会启动服务、不会调用 GitHub API、不会请求 installation token、不会真实写 check run、不会发 PR comment，也不会上传源码。

package/dist/hosted/contracts.d.ts

@@ -481,6 +481,187 @@ export interface HostedDeletionPlan {
     auditRecordRetentionDays: number;
     visibleUserMessage: string;
 }
+export type HostedRetentionAndDeletionCleanupTrigger = HostedDeletionTrigger | "retention_expired";
+export interface HostedCompactReportRetentionRecord {
+    id: string;
+    installationId: number;
+    repositoryId: number;
+    createdAt: string;
+    retentionDays?: number;
+    expiresAt?: string;
+}
+export interface HostedWorkerCheckoutCleanupState {
+    key: string;
+    identity: HostedScanIdentity;
+    status?: "active" | "deletion_pending" | "deleted";
+}
+export interface HostedRetentionAndDeletionCleanupInput {
+    trigger: HostedRetentionAndDeletionCleanupTrigger;
+    installationId: number;
+    repositoryId?: number;
+    requestedAt: string;
+    compactReports: HostedCompactReportRetentionRecord[];
+    jobs: HostedQueueCleanupJobState[];
+    workerCheckouts: HostedWorkerCheckoutCleanupState[];
+    auditRecordRetentionDays?: number;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface HostedRetentionAndDeletionCleanupAuditRecord {
+    cleanupRequestId: string;
+    trigger: HostedRetentionAndDeletionCleanupTrigger;
+    status: "planned";
+    installationId: number;
+    repositoryId?: number;
+    requestedAt: string;
+}
+export interface HostedRetentionAndDeletionCleanupPlan {
+    trigger: HostedRetentionAndDeletionCleanupTrigger;
+    scope: "repository" | "installation";
+    installationId: number;
+    repositoryId?: number;
+    requestedAt: string;
+    idempotencyKey: string;
+    idempotent: true;
+    deleteCompactReportIds: string[];
+    preserveCompactReportIds: string[];
+    cancelQueuedJobKeys: string[];
+    requestRunningCancellationJobKeys: string[];
+    preserveTerminalJobKeys: string[];
+    keepUnmatchedJobKeys: string[];
+    deleteWorkerCheckoutKeys: string[];
+    keepWorkerCheckoutKeys: string[];
+    deleteCompactReports: true;
+    cancelQueuedJobs: boolean;
+    requestRunningCancellation: boolean;
+    deleteWorkerCheckouts: boolean;
+    shouldFetchRepository: false;
+    shouldRequeueScans: false;
+    deleteRawSource: false;
+    deleteRawDiffs: false;
+    deleteSecrets: false;
+    deleteCustomerPayloads: false;
+    deleteGitHubOwnedCheckRuns: false;
+    preserveAuditRecord: true;
+    auditRecordRetentionDays: number;
+    auditRecord: HostedRetentionAndDeletionCleanupAuditRecord;
+    visibleUserMessage: string;
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+        includesWorkerCheckoutPaths: false;
+        includesPrivateUrls: false;
+        includesLowLevelCleanupErrors: false;
+    };
+}
+export declare const HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS: readonly [{
+    readonly id: "clean_ci";
+    readonly priority: "P0";
+    readonly label: "Clean CI";
+}, {
+    readonly id: "hosted_contract_tests";
+    readonly priority: "P0";
+    readonly label: "Hosted contract tests";
+}, {
+    readonly id: "webhook_replay";
+    readonly priority: "P0";
+    readonly label: "Webhook replay";
+}, {
+    readonly id: "workflow_static_checks";
+    readonly priority: "P0";
+    readonly label: "Workflow static checks";
+}, {
+    readonly id: "dependency_scan";
+    readonly priority: "P0";
+    readonly label: "Dependency scan";
+}, {
+    readonly id: "container_scan";
+    readonly priority: "P0";
+    readonly label: "Container scan";
+}, {
+    readonly id: "queue_worker_cleanup";
+    readonly priority: "P0";
+    readonly label: "Queue and worker cleanup";
+}, {
+    readonly id: "privacy_retention";
+    readonly priority: "P0";
+    readonly label: "Privacy and retention";
+}, {
+    readonly id: "monitoring_alerting";
+    readonly priority: "P0";
+    readonly label: "Monitoring and alerting";
+}, {
+    readonly id: "manual_rollback";
+    readonly priority: "P0";
+    readonly label: "Manual rollback";
+}, {
+    readonly id: "incident_response";
+    readonly priority: "P0";
+    readonly label: "Incident response";
+}, {
+    readonly id: "release_cleanup";
+    readonly priority: "P0";
+    readonly label: "Release cleanup";
+}];
+export type HostedOperationalReleaseGateRequirementId = (typeof HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS)[number]["id"];
+export type HostedOperationalReleaseGateEvidenceStatus = "passed" | "failed" | "missing" | "exception";
+export interface HostedOperationalReleaseGateEvidence {
+    id: HostedOperationalReleaseGateRequirementId;
+    status: HostedOperationalReleaseGateEvidenceStatus;
+    collectedAt?: string;
+    evidenceUrl?: string;
+    note?: string;
+    owner?: string;
+}
+export interface HostedOperationalReleaseGateInput {
+    commitSha: string;
+    scannerVersion: string;
+    deploymentTarget: string;
+    evaluatedAt: string;
+    evidence: HostedOperationalReleaseGateEvidence[];
+    releaseNotes: string;
+    containerImageDigest?: string;
+    maxEvidenceAgeDays?: number;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface HostedOperationalReleaseGateDecision {
+    commitSha: string;
+    scannerVersion: string;
+    deploymentTarget: string;
+    evaluatedAt: string;
+    requiredEvidenceCount: number;
+    requiredEvidenceIds: HostedOperationalReleaseGateRequirementId[];
+    passedEvidenceIds: HostedOperationalReleaseGateRequirementId[];
+    missingEvidenceIds: HostedOperationalReleaseGateRequirementId[];
+    failedEvidenceIds: HostedOperationalReleaseGateRequirementId[];
+    staleEvidenceIds: HostedOperationalReleaseGateRequirementId[];
+    exceptionEvidenceIds: HostedOperationalReleaseGateRequirementId[];
+    containerImageDigestRecorded: boolean;
+    releaseNotesCompliant: boolean;
+    releaseNotesForbiddenClaims: string[];
+    shouldExposeHostedEnvironment: boolean;
+    blocked: boolean;
+    localCliBoundary: {
+        localCliUsableWithoutHostedService: true;
+        accountRequiredForLocalCli: false;
+    };
+    visibleUserMessage: string;
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+        includesPrivateUrls: false;
+        modelTraining: "disabled";
+    };
+}
 export declare const HOSTED_PRIVACY_DEFAULTS: {
     readonly retentionDays: 30;
     readonly auditRecordRetentionDays: 90;
@@ -515,3 +696,10 @@ export declare function getHostedDeletionIdempotencyKey(input: {
     repositoryId?: number;
 }): string;
 export declare function createHostedDeletionPlan(input: HostedDeletionPlanInput): HostedDeletionPlan;
+export declare function getHostedRetentionAndDeletionCleanupIdempotencyKey(input: {
+    trigger: HostedRetentionAndDeletionCleanupTrigger;
+    installationId: number;
+    repositoryId?: number;
+}): string;
+export declare function planHostedRetentionAndDeletionCleanup(input: HostedRetentionAndDeletionCleanupInput): HostedRetentionAndDeletionCleanupPlan;
+export declare function evaluateHostedOperationalReleaseGate(input: HostedOperationalReleaseGateInput): HostedOperationalReleaseGateDecision;

package/dist/hosted/contracts.js

@@ -1,4 +1,18 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
+export const HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS = [
+    { id: "clean_ci", priority: "P0", label: "Clean CI" },
+    { id: "hosted_contract_tests", priority: "P0", label: "Hosted contract tests" },
+    { id: "webhook_replay", priority: "P0", label: "Webhook replay" },
+    { id: "workflow_static_checks", priority: "P0", label: "Workflow static checks" },
+    { id: "dependency_scan", priority: "P0", label: "Dependency scan" },
+    { id: "container_scan", priority: "P0", label: "Container scan" },
+    { id: "queue_worker_cleanup", priority: "P0", label: "Queue and worker cleanup" },
+    { id: "privacy_retention", priority: "P0", label: "Privacy and retention" },
+    { id: "monitoring_alerting", priority: "P0", label: "Monitoring and alerting" },
+    { id: "manual_rollback", priority: "P0", label: "Manual rollback" },
+    { id: "incident_response", priority: "P0", label: "Incident response" },
+    { id: "release_cleanup", priority: "P0", label: "Release cleanup" }
+];
 export const HOSTED_PRIVACY_DEFAULTS = {
     retentionDays: 30,
     auditRecordRetentionDays: 90,
@@ -571,10 +585,160 @@ export function createHostedDeletionPlan(input) {
         deleteCustomerPayloads: false,
         deleteGitHubOwnedCheckRuns: false,
         preserveAuditRecord: true,
-        auditRecordRetentionDays: input.auditRecordRetentionDays ?? HOSTED_PRIVACY_DEFAULTS.auditRecordRetentionDays,
+        auditRecordRetentionDays: resolveHostedAuditRecordRetentionDays(input.auditRecordRetentionDays),
         visibleUserMessage: "Hosted app-side compact reports and queued work are removed; GitHub-owned check runs remain in GitHub according to repository settings."
     };
 }
+export function getHostedRetentionAndDeletionCleanupIdempotencyKey(input) {
+    return [
+        "retention-cleanup",
+        input.trigger,
+        input.installationId,
+        input.repositoryId ?? "all"
+    ].join(":");
+}
+export function planHostedRetentionAndDeletionCleanup(input) {
+    const retentionOnly = input.trigger === "retention_expired";
+    const scope = resolveRetentionAndDeletionCleanupScope(input);
+    const repositoryId = scope === "repository" ? input.repositoryId : undefined;
+    const idempotencyKey = getHostedRetentionAndDeletionCleanupIdempotencyKey({
+        trigger: input.trigger,
+        installationId: input.installationId,
+        repositoryId
+    });
+    const reportActions = planHostedCompactReportCleanup(input, scope);
+    const queueActions = input.trigger === "retention_expired"
+        ? emptyHostedQueueCleanupActions(input.jobs)
+        : createHostedQueueCleanupPlan({
+            trigger: input.trigger,
+            installationId: input.installationId,
+            repositoryId,
+            requestedAt: input.requestedAt,
+            jobs: input.jobs
+        });
+    const checkoutActions = retentionOnly
+        ? emptyHostedWorkerCheckoutCleanupActions(input.workerCheckouts)
+        : planHostedWorkerCheckoutCleanup(input, scope);
+    return {
+        trigger: input.trigger,
+        scope,
+        installationId: input.installationId,
+        ...(repositoryId === undefined ? {} : { repositoryId }),
+        requestedAt: input.requestedAt,
+        idempotencyKey,
+        idempotent: true,
+        deleteCompactReportIds: reportActions.deleteIds,
+        preserveCompactReportIds: reportActions.preserveIds,
+        cancelQueuedJobKeys: queueActions.cancelQueuedJobKeys,
+        requestRunningCancellationJobKeys: queueActions.requestRunningCancellationJobKeys,
+        preserveTerminalJobKeys: queueActions.preserveTerminalJobKeys,
+        keepUnmatchedJobKeys: queueActions.keepUnmatchedJobKeys,
+        deleteWorkerCheckoutKeys: checkoutActions.deleteKeys,
+        keepWorkerCheckoutKeys: checkoutActions.keepKeys,
+        deleteCompactReports: true,
+        cancelQueuedJobs: !retentionOnly,
+        requestRunningCancellation: !retentionOnly,
+        deleteWorkerCheckouts: !retentionOnly,
+        shouldFetchRepository: false,
+        shouldRequeueScans: false,
+        deleteRawSource: false,
+        deleteRawDiffs: false,
+        deleteSecrets: false,
+        deleteCustomerPayloads: false,
+        deleteGitHubOwnedCheckRuns: false,
+        preserveAuditRecord: true,
+        auditRecordRetentionDays: resolveHostedAuditRecordRetentionDays(input.auditRecordRetentionDays),
+        auditRecord: {
+            cleanupRequestId: idempotencyKey,
+            trigger: input.trigger,
+            status: "planned",
+            installationId: input.installationId,
+            ...(repositoryId === undefined ? {} : { repositoryId }),
+            requestedAt: input.requestedAt
+        },
+        visibleUserMessage: "Hosted app-side compact reports and queued work are removed; GitHub-owned check runs remain in GitHub according to repository settings.",
+        privacy: {
+            includesRawSource: false,
+            includesRawDiffs: false,
+            includesSecrets: false,
+            includesCustomerPayloads: false,
+            includesWorkerCheckoutPaths: false,
+            includesPrivateUrls: false,
+            includesLowLevelCleanupErrors: false
+        }
+    };
+}
+export function evaluateHostedOperationalReleaseGate(input) {
+    const requiredEvidenceIds = HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS.map((requirement) => requirement.id);
+    const evidenceById = new Map(input.evidence.map((evidence) => [evidence.id, evidence]));
+    const maxEvidenceAgeDays = input.maxEvidenceAgeDays ?? 14;
+    const passedEvidenceIds = [];
+    const missingEvidenceIds = [];
+    const failedEvidenceIds = [];
+    const staleEvidenceIds = [];
+    const exceptionEvidenceIds = [];
+    for (const evidenceId of requiredEvidenceIds) {
+        const evidence = evidenceById.get(evidenceId);
+        if (!evidence || evidence.status === "missing" || !hasHostedGateEvidenceReference(evidence)) {
+            missingEvidenceIds.push(evidenceId);
+            continue;
+        }
+        if (evidence.status === "failed") {
+            failedEvidenceIds.push(evidenceId);
+            continue;
+        }
+        if (evidence.status === "exception") {
+            exceptionEvidenceIds.push(evidenceId);
+            continue;
+        }
+        if (!isHostedGateEvidenceFresh(evidence, input.evaluatedAt, maxEvidenceAgeDays)) {
+            staleEvidenceIds.push(evidenceId);
+            continue;
+        }
+        passedEvidenceIds.push(evidenceId);
+    }
+    const releaseNotesForbiddenClaims = findHostedReleaseNoteForbiddenClaims(input.releaseNotes);
+    const containerImageDigestRecorded = isHostedContainerImageDigest(input.containerImageDigest);
+    const blocked = missingEvidenceIds.length > 0 ||
+        failedEvidenceIds.length > 0 ||
+        staleEvidenceIds.length > 0 ||
+        exceptionEvidenceIds.length > 0 ||
+        releaseNotesForbiddenClaims.length > 0 ||
+        !containerImageDigestRecorded;
+    return {
+        commitSha: input.commitSha,
+        scannerVersion: input.scannerVersion,
+        deploymentTarget: input.deploymentTarget,
+        evaluatedAt: input.evaluatedAt,
+        requiredEvidenceCount: requiredEvidenceIds.length,
+        requiredEvidenceIds,
+        passedEvidenceIds,
+        missingEvidenceIds,
+        failedEvidenceIds,
+        staleEvidenceIds,
+        exceptionEvidenceIds,
+        containerImageDigestRecorded,
+        releaseNotesCompliant: releaseNotesForbiddenClaims.length === 0,
+        releaseNotesForbiddenClaims,
+        shouldExposeHostedEnvironment: !blocked,
+        blocked,
+        localCliBoundary: {
+            localCliUsableWithoutHostedService: true,
+            accountRequiredForLocalCli: false
+        },
+        visibleUserMessage: blocked
+            ? "Hosted exposure is blocked until every P0 gate has fresh evidence and release notes avoid pentest, certification, and full-audit claims."
+            : "Hosted exposure may proceed for this release candidate; keep the local CLI available without the hosted service.",
+        privacy: {
+            includesRawSource: false,
+            includesRawDiffs: false,
+            includesSecrets: false,
+            includesCustomerPayloads: false,
+            includesPrivateUrls: false,
+            modelTraining: HOSTED_PRIVACY_DEFAULTS.modelTraining
+        }
+    };
+}
 function rejectWebhook(reason, deliveryId) {
     return {
         accepted: false,
@@ -714,6 +878,152 @@ function queueCleanupMatches(job, input, scope) {
     }
     return scope === "installation" || job.identity.repositoryId === input.repositoryId;
 }
+function resolveRetentionAndDeletionCleanupScope(input) {
+    if (input.trigger === "installation_deleted") {
+        return "installation";
+    }
+    if (input.trigger === "retention_expired" && input.repositoryId === undefined) {
+        return "installation";
+    }
+    return "repository";
+}
+function planHostedCompactReportCleanup(input, scope) {
+    const deleteIds = [];
+    const preserveIds = [];
+    for (const report of input.compactReports) {
+        const matchesScope = retentionCleanupMatchesReport(report, input, scope);
+        const shouldDelete = matchesScope &&
+            (input.trigger !== "retention_expired" ||
+                isCompactReportExpired(report, input.requestedAt));
+        if (shouldDelete) {
+            deleteIds.push(report.id);
+        }
+        else {
+            preserveIds.push(report.id);
+        }
+    }
+    return { deleteIds, preserveIds };
+}
+function retentionCleanupMatchesReport(report, input, scope) {
+    if (report.installationId !== input.installationId) {
+        return false;
+    }
+    return scope === "installation" || report.repositoryId === input.repositoryId;
+}
+function isCompactReportExpired(report, requestedAt) {
+    const requestedAtMs = Date.parse(requestedAt);
+    if (!Number.isFinite(requestedAtMs)) {
+        return false;
+    }
+    if (report.expiresAt !== undefined) {
+        const expiresAtMs = Date.parse(report.expiresAt);
+        return Number.isFinite(expiresAtMs) && expiresAtMs <= requestedAtMs;
+    }
+    const createdAtMs = Date.parse(report.createdAt);
+    if (!Number.isFinite(createdAtMs)) {
+        return false;
+    }
+    const retentionDays = resolveHostedRetentionDays({
+        teamRequestedDays: report.retentionDays
+    });
+    return createdAtMs + retentionDays * 24 * 60 * 60 * 1000 <= requestedAtMs;
+}
+function emptyHostedQueueCleanupActions(jobs) {
+    return {
+        cancelQueuedJobKeys: [],
+        requestRunningCancellationJobKeys: [],
+        preserveTerminalJobKeys: [],
+        keepUnmatchedJobKeys: jobs.map((job) => job.key)
+    };
+}
+function planHostedWorkerCheckoutCleanup(input, scope) {
+    const deleteKeys = [];
+    const keepKeys = [];
+    for (const checkout of input.workerCheckouts) {
+        const matchesScope = retentionCleanupMatchesIdentity(checkout.identity, input, scope);
+        if (matchesScope && checkout.status !== "deleted") {
+            deleteKeys.push(checkout.key);
+        }
+        else {
+            keepKeys.push(checkout.key);
+        }
+    }
+    return { deleteKeys, keepKeys };
+}
+function emptyHostedWorkerCheckoutCleanupActions(workerCheckouts) {
+    return {
+        deleteKeys: [],
+        keepKeys: workerCheckouts.map((checkout) => checkout.key)
+    };
+}
+function retentionCleanupMatchesIdentity(identity, input, scope) {
+    if (identity.installationId !== input.installationId) {
+        return false;
+    }
+    return scope === "installation" || identity.repositoryId === input.repositoryId;
+}
+function resolveHostedAuditRecordRetentionDays(requestedDays) {
+    if (requestedDays === undefined) {
+        return HOSTED_PRIVACY_DEFAULTS.auditRecordRetentionDays;
+    }
+    return Math.min(HOSTED_PRIVACY_DEFAULTS.auditRecordRetentionDays, Math.max(1, Math.floor(requestedDays)));
+}
+function hasHostedGateEvidenceReference(evidence) {
+    return Boolean(evidence.evidenceUrl?.trim() || evidence.note?.trim());
+}
+function isHostedGateEvidenceFresh(evidence, evaluatedAt, maxEvidenceAgeDays) {
+    if (!evidence.collectedAt) {
+        return false;
+    }
+    const collectedAtMs = Date.parse(evidence.collectedAt);
+    const evaluatedAtMs = Date.parse(evaluatedAt);
+    if (!Number.isFinite(collectedAtMs) || !Number.isFinite(evaluatedAtMs)) {
+        return false;
+    }
+    const maxAgeMs = Math.max(0, Math.floor(maxEvidenceAgeDays)) * 24 * 60 * 60 * 1000;
+    const evidenceAgeMs = evaluatedAtMs - collectedAtMs;
+    return evidenceAgeMs >= 0 && evidenceAgeMs <= maxAgeMs;
+}
+function isHostedContainerImageDigest(digest) {
+    return /^sha256:[a-f0-9]{64}$/i.test(digest ?? "");
+}
+function findHostedReleaseNoteForbiddenClaims(releaseNotes) {
+    const claims = [];
+    const sentences = releaseNotes.split(/[.!?]\s+/).filter((sentence) => sentence.trim());
+    if (sentences.some((sentence) => hasPositiveHostedReleaseClaim(sentence, /\b(?:pentest|penetration test)\b/i))) {
+        claims.push("pentest_claim");
+    }
+    if (sentences.some((sentence) => hasPositiveHostedReleaseClaim(sentence, /\b(?:certification|certified)\b/i))) {
+        claims.push("certification_claim");
+    }
+    if (sentences.some((sentence) => hasPositiveHostedReleaseClaim(sentence, /\bfull(?:\s+security)?\s+audit\b/i))) {
+        claims.push("full_audit_claim");
+    }
+    return claims;
+}
+function hasPositiveHostedReleaseClaim(sentence, termPattern) {
+    const termRegex = new RegExp(termPattern.source, termPattern.flags.replace("g", ""));
+    const termMatch = termRegex.exec(sentence);
+    if (!termMatch || termMatch.index === undefined) {
+        return false;
+    }
+    const prefix = sentence.slice(Math.max(0, termMatch.index - 120), termMatch.index);
+    const lastClaimVerbIndex = lastRegexMatchIndex(prefix, /\b(?:is|are|as|provides?|delivers?|offers?|certifies?)\b/gi);
+    if (lastClaimVerbIndex === -1) {
+        return false;
+    }
+    const lastNegationIndex = lastRegexMatchIndex(prefix, /\b(?:not|never|does not|do not|is not|are not)\b/gi);
+    return lastNegationIndex < lastClaimVerbIndex;
+}
+function lastRegexMatchIndex(value, pattern) {
+    let lastIndex = -1;
+    for (const match of value.matchAll(pattern)) {
+        if (match.index !== undefined) {
+            lastIndex = match.index;
+        }
+    }
+    return lastIndex;
+}
 function isTerminalQueueStatus(status) {
     return status === "completed" || status === "failed" || status === "cancelled";
 }

package/docs/github-action.md

@@ -2,7 +2,7 @@
 
 `ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
 
-Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.14.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.16.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

package/docs/hosted-operational-release-gate.md

@@ -36,6 +36,31 @@ Every hosted release must record:
 9. Monitoring and alerting checks cover ingress, queue depth, worker failures, check run failures, and cleanup failures.
 10. Manual rollback is tested against the release candidate.
 
+## Current Source Candidate Evidence Notes
+
+The current public package release is still a local CLI and pure hosted-contract release. No hosted production environment is exposed by this release.
+
+The pure evaluator `evaluateHostedOperationalReleaseGate` and the exported `HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS` list make the gate machine-checkable for the next hosted service stage. The evaluator blocks hosted exposure unless every P0 item has fresh evidence, a `sha256:<digest>` container image digest is recorded, and release notes avoid positive pentest, certification, and full-audit claims. Explicit wording such as "not a pentest, certification, or full security audit" remains allowed.
+
+Source-level evidence notes for this release candidate:
+
+| Gate ID | Requirement | Evidence link or note | Current source status |
+| --- | --- | --- | --- |
+| `clean_ci` | Clean install, tests, build, CLI help, JSON/SARIF scan, PR-risk, npm audit, pack dry-run | Local release gate plus GitHub Actions CI run from the release commit | Passed for source package |
+| `hosted_contract_tests` | Hosted contract tests for webhook, scope, queue, worker, check summaries, cleanup, retention, and release gate evaluation | `tests/hosted-contracts.test.mjs` | Passed for pure contracts |
+| `webhook_replay` | Valid events queue work; invalid, missing, malformed, replayed, removed, and non-installed events queue nothing | Pure replay coverage in hosted webhook intake tests | Passed for pure contracts; must replay against deployed ingress before exposure |
+| `workflow_static_checks` | GitHub Actions static analysis | `actionlint` and `uvx zizmor --offline .github/workflows` | Passed for repository workflows |
+| `dependency_scan` | Dependency scan has no unresolved high or critical production findings | `npm audit --audit-level=high --registry=https://registry.npmjs.org` | Passed for source package |
+| `container_scan` | Container image scan has no unresolved high or critical runtime-layer findings | No hosted container image exists in the public package release | Not applicable to current non-hosted release; required before hosted exposure |
+| `queue_worker_cleanup` | Queue dedupe, running cancellation, terminal cleanup, worker checkout deletion, and no long-running processes | Pure queue, worker, checkout, and retention cleanup planner tests | Passed for pure contracts; must verify against deployed queue and worker before exposure |
+| `privacy_retention` | No raw source, raw diffs, secrets, customer payloads, private URLs, or full file contents; retention and uninstall cleanup are proven | Compact report, Check Run publication, retention/deletion cleanup, and docs tests | Passed for pure contracts; log sampling still required before exposure |
+| `monitoring_alerting` | Ingress, queue depth, worker failures, Check Run failures, cleanup failures, retention failures, and credential rotation alerts | Required alert list remains in this document | Documented; must attach provider evidence before exposure |
+| `manual_rollback` | Worker pause, previous artifact redeploy, queue resume, controlled ingress failure, and affected Check Run identification | Manual rollback procedure remains in this document | Documented; must execute against deployed artifact before exposure |
+| `incident_response` | Owner, backup, credential rotation, queue pause, customer communication, status path, and privacy-safe evidence collection | Incident response checklist remains in this document | Documented; must name live owners before exposure |
+| `release_cleanup` | Temporary files, package tarballs, scratch SARIF/JSON, test queues/stores, and long-running processes are removed | Local cleanup checks after each release task | Passed for local release run |
+
+For the current non-hosted package, these notes are enough to keep the repository implementation-ready while still blocking real hosted exposure until the deployment-specific evidence rows are completed with live provider links or notes.
+
 ## CI Checks
 
 Hosted release CI must include the existing public package gate:

package/docs/hosted-preimplementation-contracts.md

@@ -195,6 +195,60 @@ Cleanup failure behavior:
 - require manual cleanup review
 - preserve an audit record without exposing checkout contents
 
+## Retention And Deletion Cleanup Planner
+
+The retention and deletion cleanup planner composes the hosted cleanup contracts into one implementation-ready plan for repository removal, full app uninstall, repeated cleanup requests, and compact report retention expiry. It is a pure planner only: it does not connect to storage, mutate queues, delete files, call GitHub, retry work, or fetch repository content.
+
+Default behavior:
+
+- support repository-scoped cleanup when a repository is removed from an installation
+- support installation-scoped cleanup when the GitHub App is uninstalled
+- keep repeated cleanup idempotent with a stable cleanup key
+- delete only compact reports that match the affected installation and repository scope
+- cancel queued jobs and request running cancellation only for matching scope
+- preserve completed, failed, and cancelled terminal jobs as audit-safe terminal state
+- delete matching worker checkouts while keeping unmatched installation or repository checkouts untouched
+- expire only compact reports past their explicit `expiresAt` timestamp or derived retention window
+- cap audit record retention at the hosted default unless a stricter shorter policy is requested
+- never fetch source, requeue scans, or delete GitHub-owned Check Runs during cleanup
+
+Minimal audit record:
+
+- cleanup request ID
+- trigger
+- status
+- installation ID
+- repository ID when repository-scoped
+- requested time
+
+Privacy boundaries:
+
+- do not return raw source, raw diffs, secret values, customer payloads, private URLs, worker checkout paths, or low-level cleanup errors
+- keep user-facing deletion wording precise: hosted app-side compact reports and queued work are removed; GitHub-owned check runs remain in GitHub according to repository settings
+
+The exported helper is `planHostedRetentionAndDeletionCleanup`. It is intended to be the storage-, queue-, and worker-provider-independent contract for the first real hosted cleanup implementation.
+
+## Operational Release Gate Evaluator
+
+The operational release gate evaluator turns the hosted release gate into a pure, machine-checkable decision. It is a pure evaluator only: it does not deploy containers, inspect cloud accounts, run scanners, call GitHub, publish npm packages, or create release notes.
+
+Default behavior:
+
+- require fresh P0 evidence for clean CI, hosted contract tests, webhook replay, workflow static checks, dependency scan, container scan, queue and worker cleanup, privacy and retention, monitoring and alerting, manual rollback, incident response, and release cleanup
+- require each evidence item to include either an evidence URL or a concrete note
+- treat missing, failed, stale, or exception-marked P0 evidence as release blockers
+- require a `sha256:<digest>` container image digest before hosted exposure
+- reject release notes that make positive pentest, certification, or full-audit claims
+- preserve the local-first boundary: the local CLI remains usable without the hosted service and without an account
+
+Privacy boundaries:
+
+- return only requirement IDs, status IDs, version metadata, deployment target, and high-level decision fields
+- do not return raw source, raw diffs, secrets, customer payloads, or private URLs
+- preserve `modelTraining: disabled`
+
+The exported helper is `evaluateHostedOperationalReleaseGate`. The exported requirement list is `HOSTED_OPERATIONAL_RELEASE_GATE_REQUIREMENTS`.
+
 ## Hosted Compact Report Fixture
 
 A public hosted compact report fixture is available at [examples/hosted-compact-report.json](../examples/hosted-compact-report.json). It is intentionally synthetic and shows the report shape future hosted components can pass between the worker, check-run summary renderer, and retention cleanup logic.
@@ -256,6 +310,15 @@ Automated tests must cover:
 - worker checkout cleanup planner covers success, failure, timeout, cancellation, and cleanup_failure terminal states
 - worker checkout cleanup planner returns safe metadata only and never returns checkout paths
 - cleanup_failure requires manual cleanup review without exposing low-level cleanup errors
+- retention and deletion cleanup planner deletes only matching repository-scoped compact reports, queued jobs, and worker checkouts
+- retention and deletion cleanup planner handles full app uninstall without touching other installations
+- retention and deletion cleanup planner keeps repeated cleanup idempotent and preserves terminal jobs
+- retention cleanup expires only compact reports past their retention window
+- retention and deletion cleanup planner preserves only minimal audit records
+- operational release gate evaluator passes only when all required P0 evidence is present and fresh
+- operational release gate evaluator blocks hosted exposure when evidence is missing, failed, stale, or exception-marked
+- operational release gate evaluator blocks hosted exposure when the container digest is missing
+- operational release gate evaluator rejects positive pentest, certification, and full-audit claims while allowing explicit "not a pentest" wording
 - hosted compact report fixture remains schema-compatible and public-safe
 - summary counts with an explicit `total` are not double-counted by check-run summaries
 

package/docs/hosted-uninstall-data-deletion.md

@@ -151,6 +151,8 @@ Automated tests must cover:
 
 The current pure contract helpers live in `src/hosted/contracts.ts` and are tested by `tests/hosted-contracts.test.mjs`.
 
+The implementation-ready aggregate cleanup helper is `planHostedRetentionAndDeletionCleanup`. It composes compact report deletion, queue cancellation, running-job cancellation requests, worker checkout deletion, retention expiry, user-facing deletion wording, and minimal audit records into one provider-independent plan.
+
 ## Operational Gate
 
 The hosted operational release gate must include cleanup evidence before deployment:

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.14.0`
+- Current version: `0.16.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.14.0`
+- GitHub Release: `v0.16.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -17,7 +17,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.14.0`.
+1. Create and review a release tag such as `v0.16.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/project-handoff.md

@@ -57,9 +57,9 @@ Implemented surfaces:
 - hosted operational release gate document requiring hosted CI, webhook replay, dependency and container scanning, privacy and retention verification, worker cleanup, monitoring and alerting, manual rollback, and incident response evidence before exposure
 - hosted uninstall and data deletion document defining repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup idempotency, and user-facing deletion wording
 - hosted pricing and packaging document defining open-source CLI boundaries, free/public repo hosted behavior, private repo hosted behavior, PR comments, saved reports, team policy, optional Launch Review, and no pentest/certification/full-audit claims
-- hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, worker read-only scan planning, Check Run publication planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, and worker checkout cleanup planning
+- hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, worker read-only scan planning, Check Run publication planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, retention/deletion cleanup planning, and operational release gate evaluation
 - implementation-ready hosted GitHub App permission contract for required permissions, optional PR comment permissions, selected repository installation, and out-of-scope broad permissions
-- pure hosted GitHub App contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable scan queue idempotency, compact reports, and retention limits
+- pure hosted GitHub App contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable scan queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, and operational release gate blocking
 - GitHub issue templates for bug reports, false positives, false negatives, rule requests, and public-safe security reports
 - CODEOWNERS for source, tests, docs, workflows, Action, and package metadata
 - JSON output
@@ -116,19 +116,21 @@ Current issue set:
 - Closed hosted MVP issue: #24 webhook intake.
 - Closed hosted MVP issue: #25 idempotent queue contract.
 - Closed hosted MVP issue: #26 read-only worker checkout.
-- Open hosted MVP roadmap issues: #27 Check summaries, #28 retention/uninstall cleanup, and #29 hosted operational release gate.
+- Closed hosted MVP issue: #27 Check summaries.
+- Closed hosted MVP issue: #28 retention/uninstall cleanup.
+- Closed hosted MVP issue: #29 hosted operational release gate.
 
 CI:
 
 - Workflow: `.github/workflows/ci.yml`
 - Runs on pull requests and pushes to `main`
 - Uses `permissions: contents: read`
-- Latest verified run for the hosted read-only worker plan release succeeded
+- Latest verified run for the hosted Check Run publication release succeeded
 
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.14.0`
+- Current release line: `v0.16.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
 - Long-lived npm publish tokens should not be required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",