@trigguard/protocol 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# `@trigguard/protocol`
+
+The TrigGuard protocol defines the **contract for deterministic authorization decisions** between AI systems and execution surfaces: vocabulary (`PERMIT`, `DENY`, `SILENCE`), enforcement semantics, and the `DecisionRecord` shape used across aligned products and tooling.
+
+**This package is governance and types only** — not runtime evaluation, policy engines, or business logic. Those live elsewhere in the monorepo and **conform** to this contract.
+
+## Install
+
+```bash
+npm install @trigguard/protocol
+```
+
+*(Requires the package to be published to the npm registry under the `@trigguard` scope; see `docs/release/PROTOCOL_RELEASE.md`.)*
+
+Until publish is configured, depend on the repo:
+
+```json
+"@trigguard/protocol": "file:../packages/protocol"
+```
+
+or install from a Git URL / workspace as documented in the main [TrigGuard repository](https://github.com/TrigGuard-AI/TrigGuard).
+
+## Decision model
+
+| Decision   | Meaning (high level) |
+|------------|----------------------|
+| **PERMIT** | Authorization to proceed under policy (subject to enforcement and deployment rules). |
+| **DENY**   | Action must not proceed as requested. |
+| **SILENCE**| No authorization was issued; without authorization, execution cannot proceed (see `SILENCE_DEFINITION` export). |
+
+Policy-only layers may restrict emitted decisions to **PERMIT** / **DENY**; full protocol surfaces also use **SILENCE** where applicable.
+
+## Example import (TypeScript)
+
+```typescript
+import {
+  type Decision,
+  type DecisionRecord,
+  DECISION,
+  DECISIONS,
+  SILENCE_DEFINITION,
+} from "@trigguard/protocol";
+
+const d: Decision = "PERMIT";
+const record: DecisionRecord = {
+  decision: DECISION.PERMIT,
+  enforcement: "EXECUTED",
+  reason_code: "NO_POLICY_VIOLATION",
+  timestamp: new Date().toISOString(),
+};
+```
+
+There is **no** `evaluate()` in this package — evaluation lives in TrigGuard services and kernels. This package supplies **types and canonical constants** so callers and SDKs share one contract.
+
+## Build (maintainers / CI)
+
+From `packages/protocol`:
+
+```bash
+npm install
+npm run build
+```
+
+`build` runs `sync-contract` (when the full monorepo is present), `tsc`, and asset copy into `dist/`. Published tarballs are built via `prepack` / `prepare` before `npm publish`.
+
+## Repository
+
+Canonical source: [github.com/TrigGuard-AI/TrigGuard](https://github.com/TrigGuard-AI/TrigGuard) — `packages/protocol/`.
+
+For installation paths and release tagging, see:
+
+- `docs/developers/INSTALL_PROTOCOL.md`
+- `docs/release/PROTOCOL_RELEASE.md`
+
+## Legacy note (snapshot)
+
+`src/contracts/decision_contract.json` is kept in sync with `core/contracts/decision_contract.json` via `npm run sync-contract` in the monorepo. **Do not edit kernel contracts from this README** — follow governance and protocol integrity processes in the main repo.

package/dist/contracts/decision_contract.json

@@ -0,0 +1,9 @@
+{
+  "decision": ["PERMIT", "DENY"],
+  "reasonCode": [
+    "NO_POLICY_VIOLATION",
+    "HIGH_RISK_SPEND",
+    "RSD_AUTOMATION_CONFLICT",
+    "NO_MATCHING_POLICY"
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @trigguard/protocol — canonical vocabulary and record shape for TrigGuard surfaces.
+ * Policy/evaluation layers may emit only PERMIT|DENY; full protocol includes SILENCE.
+ * Reason codes are snapshotted from core/contracts/decision_contract.json (see sync-contract script).
+ */
+import decisionContract from "./contracts/decision_contract.json";
+/** Full protocol decision set (remote eval / product surfaces). */
+export type Decision = "PERMIT" | "DENY" | "SILENCE";
+/** Policy contract layer decisions only (matches decision_contract.json `decision`). */
+export type PolicyDecision = "PERMIT" | "DENY";
+export type Enforcement = "EXECUTED" | "BLOCKED";
+export declare const DECISION: {
+    readonly PERMIT: "PERMIT";
+    readonly DENY: "DENY";
+    readonly SILENCE: "SILENCE";
+};
+export declare const ENFORCEMENT: {
+    readonly EXECUTED: "EXECUTED";
+    readonly BLOCKED: "BLOCKED";
+};
+/** Ordered canonical sets for consumers (CI, SDKs). */
+export declare const DECISIONS: readonly ["PERMIT", "DENY", "SILENCE"];
+export declare const ENFORCEMENTS: readonly ["EXECUTED", "BLOCKED"];
+/**
+ * Canonical SILENCE explanation for public and SDK surfaces.
+ * Keep in sync with site governance / protocol docs.
+ */
+export declare const SILENCE_DEFINITION = "SILENCE means no authorization was issued. Without authorization, execution cannot proceed.";
+/** Reason codes derived from core/contracts/decision_contract.json (kept in sync by sync-contract). */
+export declare const REASON_CODES: readonly string[];
+export type ReasonCode = (typeof decisionContract.reasonCode)[number];
+export interface DecisionRecord {
+    decision: Decision;
+    enforcement: Enforcement;
+    /** Prefer values from REASON_CODES when representing policy outcomes. */
+    reason_code: string;
+    timestamp: string;
+}
+/** Embedded contract snapshot (authoritative registry for reason codes at policy layer). */
+export { decisionContract };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,gBAAgB,MAAM,oCAAoC,CAAC;AAElE,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAErD,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/C,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjD,eAAO,MAAM,QAAQ;;;;CAIwB,CAAC;AAE9C,eAAO,MAAM,WAAW;;;CAGwB,CAAC;AAEjD,uDAAuD;AACvD,eAAO,MAAM,SAAS,wCAAyC,CAAC;AAEhE,eAAO,MAAM,YAAY,kCAAmC,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,gGACgE,CAAC;AAEhG,uGAAuG;AACvG,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAgC,CAAC;AAE3E,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,gBAAgB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,4FAA4F;AAC5F,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * @trigguard/protocol — canonical vocabulary and record shape for TrigGuard surfaces.
+ * Policy/evaluation layers may emit only PERMIT|DENY; full protocol includes SILENCE.
+ * Reason codes are snapshotted from core/contracts/decision_contract.json (see sync-contract script).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionContract = exports.REASON_CODES = exports.SILENCE_DEFINITION = exports.ENFORCEMENTS = exports.DECISIONS = exports.ENFORCEMENT = exports.DECISION = void 0;
+const decision_contract_json_1 = __importDefault(require("./contracts/decision_contract.json"));
+exports.decisionContract = decision_contract_json_1.default;
+exports.DECISION = {
+    PERMIT: "PERMIT",
+    DENY: "DENY",
+    SILENCE: "SILENCE",
+};
+exports.ENFORCEMENT = {
+    EXECUTED: "EXECUTED",
+    BLOCKED: "BLOCKED",
+};
+/** Ordered canonical sets for consumers (CI, SDKs). */
+exports.DECISIONS = ["PERMIT", "DENY", "SILENCE"];
+exports.ENFORCEMENTS = ["EXECUTED", "BLOCKED"];
+/**
+ * Canonical SILENCE explanation for public and SDK surfaces.
+ * Keep in sync with site governance / protocol docs.
+ */
+exports.SILENCE_DEFINITION = "SILENCE means no authorization was issued. Without authorization, execution cannot proceed.";
+/** Reason codes derived from core/contracts/decision_contract.json (kept in sync by sync-contract). */
+exports.REASON_CODES = decision_contract_json_1.default.reasonCode;

package/dist/schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TrigGuardCanonicalDecisionRecord",
+  "description": "Authoritative shape for protocol decision records. reason_code values align with core/contracts/decision_contract.json reasonCode registry.",
+  "type": "object",
+  "required": ["decision", "enforcement", "reason_code", "timestamp"],
+  "properties": {
+    "decision": {
+      "type": "string",
+      "enum": ["PERMIT", "DENY", "SILENCE"]
+    },
+    "enforcement": {
+      "type": "string",
+      "enum": ["EXECUTED", "BLOCKED"]
+    },
+    "reason_code": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@trigguard/protocol",
+  "version": "0.1.0",
+  "description": "Canonical TrigGuard protocol types and contract snapshots (governance layer, not business logic).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "sync-contract": "node scripts/sync-contract.mjs",
+    "build": "npm run sync-contract && tsc && node scripts/copy-assets.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "trigguard",
+    "protocol",
+    "governance"
+  ],
+  "license": "SEE LICENSE IN REPO",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TrigGuard-AI/TrigGuard"
+  },
+  "devDependencies": {
+    "typescript": "~5.6.3"
+  }
+}