@neurcode-ai/contracts 0.2.3 → 0.2.5

package/dist/runtime-risk-pack-v1.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Runtime Risk Pack Report (Iteration 11 — AppSec-Adjacent Runtime Risk Pack).
+ *
+ * Neurcode is a runtime control plane for AI coding agents — a seatbelt and
+ * flight recorder. It is NOT an AppSec scanner, SAST engine, CVE/vulnerability
+ * database, or code-review bot. This report states, in one honest source-free
+ * surface, which AppSec-adjacent *runtime* boundaries the agent must obey
+ * BEFORE a write lands — and exactly what enforcement each one carries.
+ *
+ * The enforcement is NOT authored here. The CLI builder
+ * (`packages/cli/src/utils/runtime-risk-pack.ts`) derives every category's
+ * `family`, `enforcementAction`, `truthTier`, and `reasonIds` by running the
+ * canonical Runtime Safety Kernel classifiers (`evaluateRuntimeSafetyCheck`
+ * over representative fixture paths) — it never re-implements classify logic and
+ * never introduces a second taxonomy. The `family` type is the same
+ * {@link ManagerEvidenceRiskFamily} the kernel and manager-evidence dashboard
+ * use, so no new RuntimeSafetyFamily can drift in.
+ *
+ * Source-free by construction: category ids, buyer-facing labels, kernel reason
+ * codes, families, enforcement-action strings, truth tiers, counts, and
+ * representative *fixture* paths (synthetic, not repository source paths) —
+ * never source bodies, diffs, prompts, secrets, or CVE text.
+ */
+import type { ManagerEvidenceRiskFamily } from './manager-evidence';
+export declare const RUNTIME_RISK_PACK_SCHEMA_VERSION: "neurcode.runtime-risk-pack.v1";
+/** The eight AppSec-adjacent runtime-risk categories on the Iteration 11 roadmap. */
+export declare const RUNTIME_RISK_CATEGORY_IDS: readonly ["dependency_manifest_change", "script_lifecycle_risk", "secret_like_content", "auth_rbac_edit", "crypto_session_edit", "migration_edit", "network_boundary_edit", "ci_cd_edit"];
+export type RuntimeRiskCategoryId = (typeof RUNTIME_RISK_CATEGORY_IDS)[number];
+export declare function isRuntimeRiskCategoryId(value: unknown): value is RuntimeRiskCategoryId;
+/** Enforcement vocabulary — mirrors the kernel `RuntimeSafetyEnforcementAction`. */
+export type RuntimeRiskEnforcementAction = 'allow' | 'warn' | 'approval_required' | 'block';
+/** Truth tier — mirrors the kernel `RuntimeSafetyTruthTier` (RSK truth tiers). */
+export type RuntimeRiskTruthTier = 'deterministic_fact' | 'bounded_inference' | 'advisory';
+/**
+ * How completely the kernel covers a category today.
+ *  - `enforced`        — a deterministic kernel rule governs this surface.
+ *  - `enforced_partial`— governed, but with an honest, named coverage gap
+ *    (e.g. CI/CD is GitHub-Actions-only; other CI systems are not yet matched).
+ */
+export type RuntimeRiskCoverage = 'enforced' | 'enforced_partial';
+export interface RuntimeRiskCategory {
+    id: RuntimeRiskCategoryId;
+    /** Buyer-facing label. */
+    label: string;
+    /** Verbatim roadmap bullet this category answers. */
+    roadmapBullet: string;
+    /**
+     * The existing kernel family this category maps to. No Iteration 11 category
+     * introduces a new family — network folds into `infra_deploy_boundary`,
+     * crypto/session into `auth_rbac_boundary` / `credential_or_secret`.
+     */
+    family: ManagerEvidenceRiskFamily;
+    /**
+     * Optional doctor-only sub-label that gives buyers precision without a new
+     * top-level family (e.g. `network_boundary`, `crypto_session`).
+     */
+    subLabel: string | null;
+    /**
+     * Default enforcement action under ENTERPRISE_RUNTIME_SAFETY_V1 for a
+     * representative surface — copied from the kernel decision, never re-authored.
+     */
+    enforcementAction: RuntimeRiskEnforcementAction;
+    truthTier: RuntimeRiskTruthTier;
+    coverage: RuntimeRiskCoverage;
+    /** Kernel reason codes that backed the representative classification. */
+    reasonIds: string[];
+    /** Representative source-free fixture paths showing the classifier fires. */
+    sampleSurfaces: string[];
+    /** Honest scope notes / known coverage gaps. */
+    limitations: string[];
+}
+/** External AppSec finding sources we may ingest as advisory context later. */
+export declare const RUNTIME_RISK_ADVISORY_SOURCES: readonly ["endor", "snyk", "github_advanced_security"];
+export type RuntimeRiskAdvisorySource = (typeof RUNTIME_RISK_ADVISORY_SOURCES)[number];
+/**
+ * Shape a future advisory finding would take once import is wired. Findings are
+ * advisory context only — never enforcement, never a CVE claim Neurcode makes.
+ */
+export interface RuntimeRiskAdvisoryFinding {
+    source: RuntimeRiskAdvisorySource;
+    /** Repo-relative path the external tool flagged (no source body). */
+    path: string;
+    /** External tool's own severity label, passed through verbatim. */
+    externalSeverity: string;
+    /** Mapped kernel family for cross-referencing — advisory only. */
+    family: ManagerEvidenceRiskFamily | null;
+    truthTier: 'advisory';
+}
+export type RuntimeRiskAdvisoryStatus = 'not_wired';
+export interface RuntimeRiskAdvisoryImport {
+    source: RuntimeRiskAdvisorySource;
+    status: RuntimeRiskAdvisoryStatus;
+    /** Always empty in V1 — ingest is deferred to a later iteration. */
+    findings: RuntimeRiskAdvisoryFinding[];
+    note: string;
+}
+/**
+ * The pilot evidence pack (`pilot export`) buckets surfaces with its own coarse
+ * keyword classifier. That taxonomy is intentionally left unchanged (it has a
+ * stable content hash). This map documents how a kernel family is reported there
+ * so the two surfaces are legible together — it does NOT re-author either side.
+ */
+export interface RuntimeRiskTaxonomyMapping {
+    kernelFamily: ManagerEvidenceRiskFamily;
+    pilotEvidenceFamilies: string[];
+    note: string;
+}
+export interface RuntimeRiskAppSecPositioning {
+    /** The Iteration 11 exit-criterion sentence. */
+    statement: string;
+    /** What the runtime risk pack does. */
+    weDo: string[];
+    /** What it explicitly does NOT do (no scanner / SAST / CVE / review-bot). */
+    weDoNot: string[];
+}
+export interface RuntimeRiskPackReport {
+    schemaVersion: typeof RUNTIME_RISK_PACK_SCHEMA_VERSION;
+    generatedAt: string;
+    cliVersion: string | null;
+    /** The policy profile id whose default actions were resolved. */
+    policyId: string;
+    /** Plan-control mode the actions were resolved under. */
+    planMode: string;
+    categories: RuntimeRiskCategory[];
+    summary: {
+        totalCategories: number;
+        enforced: number;
+        enforcedPartial: number;
+        byAction: Record<RuntimeRiskEnforcementAction, number>;
+        /** Distinct kernel families touched (subset of MANAGER_EVIDENCE_RISK_FAMILIES). */
+        families: ManagerEvidenceRiskFamily[];
+    };
+    taxonomyMapping: RuntimeRiskTaxonomyMapping[];
+    advisoryImports: RuntimeRiskAdvisoryImport[];
+    appSec: RuntimeRiskAppSecPositioning;
+    notes: string[];
+}
+//# sourceMappingURL=runtime-risk-pack-v1.d.ts.map

package/dist/runtime-risk-pack-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-risk-pack-v1.d.ts","sourceRoot":"","sources":["../src/runtime-risk-pack-v1.ts"],"names":[],"mappings":"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"}

package/dist/runtime-risk-pack-v1.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Runtime Risk Pack Report (Iteration 11 — AppSec-Adjacent Runtime Risk Pack).
+ *
+ * Neurcode is a runtime control plane for AI coding agents — a seatbelt and
+ * flight recorder. It is NOT an AppSec scanner, SAST engine, CVE/vulnerability
+ * database, or code-review bot. This report states, in one honest source-free
+ * surface, which AppSec-adjacent *runtime* boundaries the agent must obey
+ * BEFORE a write lands — and exactly what enforcement each one carries.
+ *
+ * The enforcement is NOT authored here. The CLI builder
+ * (`packages/cli/src/utils/runtime-risk-pack.ts`) derives every category's
+ * `family`, `enforcementAction`, `truthTier`, and `reasonIds` by running the
+ * canonical Runtime Safety Kernel classifiers (`evaluateRuntimeSafetyCheck`
+ * over representative fixture paths) — it never re-implements classify logic and
+ * never introduces a second taxonomy. The `family` type is the same
+ * {@link ManagerEvidenceRiskFamily} the kernel and manager-evidence dashboard
+ * use, so no new RuntimeSafetyFamily can drift in.
+ *
+ * Source-free by construction: category ids, buyer-facing labels, kernel reason
+ * codes, families, enforcement-action strings, truth tiers, counts, and
+ * representative *fixture* paths (synthetic, not repository source paths) —
+ * never source bodies, diffs, prompts, secrets, or CVE text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_RISK_ADVISORY_SOURCES = exports.RUNTIME_RISK_CATEGORY_IDS = exports.RUNTIME_RISK_PACK_SCHEMA_VERSION = void 0;
+exports.isRuntimeRiskCategoryId = isRuntimeRiskCategoryId;
+exports.RUNTIME_RISK_PACK_SCHEMA_VERSION = 'neurcode.runtime-risk-pack.v1';
+/** The eight AppSec-adjacent runtime-risk categories on the Iteration 11 roadmap. */
+exports.RUNTIME_RISK_CATEGORY_IDS = [
+    'dependency_manifest_change',
+    'script_lifecycle_risk',
+    'secret_like_content',
+    'auth_rbac_edit',
+    'crypto_session_edit',
+    'migration_edit',
+    'network_boundary_edit',
+    'ci_cd_edit',
+];
+function isRuntimeRiskCategoryId(value) {
+    return typeof value === 'string' && exports.RUNTIME_RISK_CATEGORY_IDS.includes(value);
+}
+/* ── D6: advisory import stub (schema-forward only; no ingest in V1) ────────── */
+/** External AppSec finding sources we may ingest as advisory context later. */
+exports.RUNTIME_RISK_ADVISORY_SOURCES = ['endor', 'snyk', 'github_advanced_security'];
+//# sourceMappingURL=runtime-risk-pack-v1.js.map

package/dist/runtime-risk-pack-v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-risk-pack-v1.js","sourceRoot":"","sources":["../src/runtime-risk-pack-v1.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAoBH,0DAEC;AAlBY,QAAA,gCAAgC,GAAG,+BAAwC,CAAC;AAEzF,qFAAqF;AACxE,QAAA,yBAAyB,GAAG;IACvC,4BAA4B;IAC5B,uBAAuB;IACvB,qBAAqB;IACrB,gBAAgB;IAChB,qBAAqB;IACrB,gBAAgB;IAChB,uBAAuB;IACvB,YAAY;CACJ,CAAC;AAIX,SAAgB,uBAAuB,CAAC,KAAc;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,iCAA+C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACvG,CAAC;AAgDD,mFAAmF;AAEnF,+EAA+E;AAClE,QAAA,6BAA6B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,0BAA0B,CAAU,CAAC"}

package/package.json

@@ -1,18 +1,12 @@
 {
   "name": "@neurcode-ai/contracts",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Shared JSON contracts for Neurcode CLI, API, action, IDE, and MCP surfaces",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "tsx --test src/*.test.ts",
-    "prepare": "npm run build"
-  },
   "license": "MIT",
   "dependencies": {},
   "publishConfig": {
@@ -22,5 +16,10 @@
     "@types/node": "^20.10.0",
     "tsx": "^4.20.6",
     "typescript": "^5.3.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsx --test src/*.test.ts"
   }
-}
+}