@rocketlang/aegis-guard 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 ANKR Labs / Capt. Anil Sharma
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+The full text of the GNU Affero General Public License v3 is available at:
+https://www.gnu.org/licenses/agpl-3.0.txt
+
+ADDITIONAL TERMS (permitted under AGPL §7):
+
+If you run a modified version of this software as a network service,
+you must make the complete source code of the modified version available
+to all users of that service under the terms of this license.
+
+Commercial use, including SaaS deployments and enterprise integrations,
+requires a separate commercial license. Contact: captain@ankr.in

package/README.md

@@ -0,0 +1,129 @@
+# @rocketlang/aegis-guard
+
+AEGIS Guard SDK — reusable approval-token, nonce, idempotency, SENSE, and quality-evidence primitives for AEGIS-governed services.
+
+**Carbonx proved the locks. Batch 93 makes the locks reusable.**
+
+The Five Locks were proven across 13 batches (62–74) of carbonx-backend. This package extracts them into a service-agnostic SDK so any AEGIS-governed service can adopt them without copy-pasting bespoke logic.
+
+## Five Locks
+
+| Lock | Primitive | Rule |
+|---|---|---|
+| LOCK_1 — decision | `verifyApprovalToken` | AEG-E-016 |
+| LOCK_2 — identity | `verifyScopedApprovalToken` | AEG-E-016 |
+| LOCK_3 — observability | `emitAegisSenseEvent` | CA-003, AEG-HG-2B-003/005 |
+| LOCK_4 — rollback | `checkIdempotency` | AEG-HG-2B-006 |
+| LOCK_5 — idempotency | `verifyAndConsumeNonce` | AEG-HG-2B-006 |
+
+## Install
+
+```bash
+bun add @rocketlang/aegis-guard
+# or
+npm install @rocketlang/aegis-guard
+```
+
+## Usage
+
+### LOCK_1 + LOCK_2 — decision + identity
+
+```typescript
+import { verifyApprovalToken, verifyScopedApprovalToken } from '@rocketlang/aegis-guard';
+
+// LOCK_1 — base token verification (service_id + capability + operation)
+const payload = verifyApprovalToken(token, 'my-service', 'settle', 'record_settle');
+
+// LOCK_2 — scoped verification (add service-specific field bindings)
+const payload = verifyScopedApprovalToken(
+  token, 'my-service', 'settle', 'record_settle',
+  { vessel_id: args.vesselId, amount: args.amount },
+);
+```
+
+### LOCK_3 — observability (SENSE)
+
+```typescript
+import { emitAegisSenseEvent, digestApprovalToken, configureSenseTransport } from '@rocketlang/aegis-guard';
+
+// Wire your logger (default: process.stdout JSON)
+configureSenseTransport((event) => logger.info(event, `SENSE:${event.event_type}`));
+
+emitAegisSenseEvent({
+  event_type: 'allowance.settle',
+  service_id: 'my-service',
+  capability: 'settle',
+  operation: 'record_settle',
+  before_snapshot: { status: 'pending' },
+  after_snapshot:  { status: 'settled' },
+  delta:           { status: 'pending→settled' },
+  emitted_at: new Date().toISOString(),
+  irreversible: true,
+  correlation_id: req.headers['x-correlation-id'],
+  approval_token_ref: digestApprovalToken(token), // 24-hex digest, never raw token
+});
+```
+
+### LOCK_4 — rollback guard (idempotency check)
+
+```typescript
+import { checkIdempotency, buildIdempotencyFingerprint } from '@rocketlang/aegis-guard';
+
+const existing = await db.findByExternalRef(args.externalRef);
+const fp = buildIdempotencyFingerprint({ amount: args.amount, vessel_id: args.vesselId });
+const { isDuplicate, safeNoOp } = checkIdempotency(args.externalRef, existing, fp, existing?.fingerprint);
+
+if (isDuplicate && safeNoOp) return existing; // safe no-op
+if (isDuplicate && !safeNoOp) throw new Error('payload mismatch on duplicate externalRef');
+```
+
+### LOCK_5 — nonce replay prevention
+
+```typescript
+import { verifyAndConsumeNonce } from '@rocketlang/aegis-guard';
+
+// Requires nonce in payload; throws IrrNoApprovalError on missing or replayed nonce
+await verifyAndConsumeNonce(payload, redisNonceStore);
+```
+
+### Quality evidence
+
+```typescript
+import { buildQualityMaskAtPromotion, meetsHgQualityRequirement } from '@rocketlang/aegis-guard';
+
+const mask = buildQualityMaskAtPromotion({
+  tests_passed: true,
+  rollback_tested: true,
+  audit_artifact_produced: true,
+});
+
+const ready = meetsHgQualityRequirement('HG-2B-financial', mask);
+```
+
+## NonceStore — production wiring
+
+The default `defaultNonceStore` is in-memory (single-process only). Multi-instance deployments must provide a Redis-backed store:
+
+```typescript
+import { type NonceStore } from '@rocketlang/aegis-guard';
+
+const redisNonceStore: NonceStore = {
+  async consumeNonce(nonce, ttlMs) {
+    const key = `aegis:nonce:${nonce}`;
+    const result = await redis.set(key, '1', 'NX', 'PX', ttlMs);
+    if (result === null) return false; // already consumed
+    return true;
+    // throws propagate to callers → fail CLOSED (AEG-HG-2B-006)
+  },
+};
+```
+
+## Schema
+
+- `quality_mask_at_promotion`: bits 0–11, `aegis-quality-16bit-v1`
+- `quality_drift_score`: bits 12–15, `aegis-quality-16bit-v1`
+- AEG-Q-003 invariant: bits 12–15 must **never** be set in `quality_mask_at_promotion`
+
+## License
+
+AGPL-3.0 — Capt. Anil Sharma, powerpbox.org

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@rocketlang/aegis-guard",
+  "version": "0.1.0",
+  "description": "AEGIS Guard SDK — reusable approval-token, nonce, idempotency, SENSE, and quality-evidence primitives for AEGIS-governed services",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "author": "Capt. Anil Sharma <capt.anil.sharma@powerpbox.org>",
+  "homepage": "https://github.com/rocketlang/aegis/tree/main/packages/aegis-guard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rocketlang/aegis.git",
+    "directory": "packages/aegis-guard"
+  },
+  "bugs": {
+    "url": "https://github.com/rocketlang/aegis/issues"
+  },
+  "keywords": [
+    "aegis",
+    "aegis-guard",
+    "approval-token",
+    "nonce",
+    "idempotency",
+    "sense",
+    "quality-mask",
+    "hg-2b",
+    "five-locks",
+    "agentic-ai",
+    "ai-governance",
+    "ai-agent-safety"
+  ],
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test tests/aegis-guard.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "aegis": {
+    "batch": 93,
+    "five_locks_proof": "carbonx-backend batches 62-74",
+    "doctrine": "Carbonx proved the locks. Batch 93 makes the locks reusable."
+  }
+}

package/src/approval-token.ts

@@ -0,0 +1,142 @@
+// @rule:AEG-E-016 — approval tokens are scoped to service_id + capability + operation
+// @rule:AEG-HG-2B-005 — approval token references in SENSE use digest, not raw token material
+// @rule:AEG-HG-2B-006 — nonce protects the approval; idempotency protects the operation (separate locks)
+
+import { createHash } from 'crypto';
+import { IrrNoApprovalError } from './errors.js';
+import { type NonceStore, defaultNonceStore } from './nonce.js';
+
+// Token may arrive up to 60s before local clock (NTP tolerance).
+const CLOCK_SKEW_MS = 60_000;
+
+export interface ApprovalTokenPayload {
+  service_id: string;
+  capability: string;
+  operation: string;
+  issued_at: number;
+  expires_at: number;
+  issued_by?: string;
+  nonce?: string;
+  status?: 'approved' | 'revoked' | 'denied';
+  [key: string]: unknown;
+}
+
+// @rule:AEG-HG-2B-005 — SENSE stores proof reference, not proof secret.
+// Returns first 24 hex chars of SHA-256 (96 bits) — sufficient for correlation, not reconstruction.
+export function digestApprovalToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex').slice(0, 24);
+}
+
+// @rule:AEG-E-016 — test/dev helper: encode a payload as base64url JSON.
+// Production tokens are minted by the AEGIS PROOF system (port 4850), not by services.
+export function mintApprovalToken(payload: ApprovalTokenPayload): string {
+  return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+
+// @rule:AEG-E-016 — token must match service_id + capability + operation exactly.
+// Token format: base64url(JSON). Production replacement: JWT signed by AEGIS key at port 4850.
+export function verifyApprovalToken(
+  token: string,
+  expectedServiceId: string,
+  expectedCapability: string,
+  expectedOperation: string,
+): ApprovalTokenPayload {
+  let payload: ApprovalTokenPayload;
+
+  try {
+    const decoded = Buffer.from(token, 'base64url').toString('utf8');
+    payload = JSON.parse(decoded) as ApprovalTokenPayload;
+  } catch {
+    throw new IrrNoApprovalError(expectedCapability, 'token could not be decoded');
+  }
+
+  if (payload.service_id !== expectedServiceId) {
+    throw new IrrNoApprovalError(
+      expectedCapability,
+      `AEG-E-016: token scoped to '${payload.service_id}', not '${expectedServiceId}'`,
+    );
+  }
+
+  if (payload.capability !== expectedCapability) {
+    throw new IrrNoApprovalError(
+      expectedCapability,
+      `AEG-E-016: token capability '${payload.capability}' does not match '${expectedCapability}'`,
+    );
+  }
+
+  if (payload.operation !== expectedOperation) {
+    throw new IrrNoApprovalError(
+      expectedCapability,
+      `AEG-E-016: token operation '${payload.operation}' does not match '${expectedOperation}'`,
+    );
+  }
+
+  if (Date.now() > payload.expires_at) {
+    throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token expired');
+  }
+
+  if (payload.issued_at !== undefined && payload.issued_at > Date.now() + CLOCK_SKEW_MS) {
+    throw new IrrNoApprovalError(
+      expectedCapability,
+      'AEG-E-016: token issued_at is in the future (clock skew > 60s or forged timestamp)',
+    );
+  }
+
+  return payload;
+}
+
+// @rule:AEG-HG-2B-006 — consume nonce before any state mutation; missing nonce = hard reject.
+// Nonce TTL is bounded by token lifetime; store unavailable = fail CLOSED (throws, never open).
+export async function verifyAndConsumeNonce(
+  payload: ApprovalTokenPayload,
+  store: NonceStore = defaultNonceStore,
+): Promise<void> {
+  if (!payload.nonce) {
+    throw new IrrNoApprovalError(
+      payload.capability,
+      'AEG-E-016: irreversible operation requires nonce for replay prevention',
+    );
+  }
+  const ttlMs = Math.max(0, payload.expires_at - Date.now());
+  const consumed = await store.consumeNonce(payload.nonce, ttlMs);
+  if (!consumed) {
+    throw new IrrNoApprovalError(
+      payload.capability,
+      `AEG-E-016: nonce '${payload.nonce}' already consumed — approval replay rejected`,
+    );
+  }
+}
+
+// @rule:AEG-E-016 — HG-2B: verify scope fields declared by the caller service.
+// requiredScope: Record<string, unknown> — caller declares which fields to bind; SDK enforces them.
+// Service-agnostic: the caller owns the field names; the SDK never names domain concepts.
+export function verifyScopedApprovalToken(
+  token: string,
+  expectedServiceId: string,
+  expectedCapability: string,
+  expectedOperation: string,
+  requiredScope: Record<string, unknown>,
+): ApprovalTokenPayload {
+  const payload = verifyApprovalToken(
+    token, expectedServiceId, expectedCapability, expectedOperation,
+  );
+
+  if (payload.status === 'revoked') {
+    throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token revoked');
+  }
+  if (payload.status === 'denied') {
+    throw new IrrNoApprovalError(expectedCapability, 'AEG-E-016: token denied');
+  }
+
+  for (const [field, contextValue] of Object.entries(requiredScope)) {
+    const tokenValue = payload[field];
+    if (tokenValue !== contextValue) {
+      throw new IrrNoApprovalError(
+        expectedCapability,
+        `AEG-E-016: token ${field} '${String(tokenValue)}' does not match scope '${String(contextValue)}'`,
+      );
+    }
+  }
+
+  return payload;
+}

package/src/envelope.ts

@@ -0,0 +1,119 @@
+// @ankr/aegis-guard — Agent Session Envelope helpers (ASE-T020)
+//
+// issueEnvelope  — POST /api/v1/aegis/session   — proxy-native agent frameworks use this at startup
+// verifyEnvelope — GET  /api/v1/aegis/sessions/:id/audit — check seal integrity + drift
+//
+// @rule:ASE-001 every proxy-native agent session must call issueEnvelope before its first LLM call
+// @rule:ASE-002 sealed_hash is computed by Aegis at issuance and returned in the response
+// @rule:INF-ASE-002 if sealed_hash_verified=false the session must be quarantined immediately
+
+export interface IssueEnvelopeParams {
+  /** agent_type must be 'proxy-native' for frameworks calling this directly */
+  agent_type?: "proxy-native" | "hook-native";
+  service_key?: string;
+  tenant_id?: string;
+  trust_mask?: number;
+  perm_mask?: number;
+  class_mask?: number;
+  /** Capabilities declared at birth — must be a subset of trust_mask. Empty = conservative default. */
+  declared_caps?: string[];
+  budget_usd?: number;
+  parent_session_id?: string;
+  /** Override the Aegis dashboard URL (default: AEGIS_URL env or http://localhost:4850) */
+  aegis_url?: string;
+}
+
+export interface EnvelopeIssueResult {
+  session_id: string;
+  agent_id: string;
+  sealed_hash: string;
+  issued_at: string;
+  expires_at: string;
+  budget_usd: number;
+  declared_caps: string[];
+  perm_mask: number;
+  class_mask: number;
+}
+
+export interface EnvelopeVerifyResult {
+  session_id: string;
+  /** true = sealed_hash matches stored fields. false = tampered — quarantine immediately. @rule:INF-ASE-002 */
+  verified: boolean;
+  drift_detected: boolean;
+  drift_set: string[];
+  declared_caps: string[];
+  actual_caps_used: string[];
+  budget_usd: number;
+  budget_used_usd: number;
+}
+
+function aegisBase(override?: string): string {
+  return override ?? process.env.AEGIS_URL ?? "http://localhost:4850";
+}
+
+// @rule:ASE-001 issue a sealed envelope before the first action
+export async function issueEnvelope(params: IssueEnvelopeParams): Promise<EnvelopeIssueResult> {
+  const url = `${aegisBase(params.aegis_url)}/api/v1/aegis/session`;
+  const body: Record<string, unknown> = {
+    agent_type: params.agent_type ?? "proxy-native",
+  };
+  if (params.service_key)       body.service_key       = params.service_key;
+  if (params.tenant_id)         body.tenant_id         = params.tenant_id;
+  if (params.trust_mask != null) body.trust_mask       = params.trust_mask;
+  if (params.perm_mask != null)  body.perm_mask        = params.perm_mask;
+  if (params.class_mask != null) body.class_mask       = params.class_mask;
+  if (params.declared_caps)     body.declared_caps     = params.declared_caps;
+  if (params.budget_usd != null) body.budget_usd       = params.budget_usd;
+  if (params.parent_session_id)  body.parent_session_id = params.parent_session_id;
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => resp.statusText);
+    throw new Error(`issueEnvelope failed (${resp.status}): ${text}`);
+  }
+
+  const data = await resp.json() as Record<string, unknown>;
+  return {
+    session_id:    String(data.session_id ?? ""),
+    agent_id:      String(data.agent_id ?? data.session_id ?? ""),
+    sealed_hash:   String(data.sealed_hash ?? ""),
+    issued_at:     String(data.issued_at ?? ""),
+    expires_at:    String(data.expires_at ?? ""),
+    budget_usd:    Number(data.budget_usd ?? 0),
+    declared_caps: Array.isArray(data.declared_caps) ? data.declared_caps as string[] : [],
+    perm_mask:     Number(data.perm_mask ?? data.trust_mask ?? 0),
+    class_mask:    Number(data.class_mask ?? 0xFFFF),
+  };
+}
+
+// @rule:INF-ASE-002 caller must quarantine if verified=false
+export async function verifyEnvelope(
+  sessionId: string,
+  options?: { aegis_url?: string },
+): Promise<EnvelopeVerifyResult> {
+  const url = `${aegisBase(options?.aegis_url)}/api/v1/aegis/sessions/${encodeURIComponent(sessionId)}/audit`;
+
+  const resp = await fetch(url);
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => resp.statusText);
+    throw new Error(`verifyEnvelope failed (${resp.status}): ${text}`);
+  }
+
+  const data = await resp.json() as Record<string, unknown>;
+  const drift_set: string[] = Array.isArray(data.drift_set) ? data.drift_set as string[] : [];
+  return {
+    session_id:        sessionId,
+    verified:          Boolean(data.sealed_hash_verified ?? false),
+    drift_detected:    Boolean(data.drift_detected ?? drift_set.length > 0),
+    drift_set,
+    declared_caps:     Array.isArray(data.declared_caps)     ? data.declared_caps as string[]    : [],
+    actual_caps_used:  Array.isArray(data.actual_caps_used)  ? data.actual_caps_used as string[] : [],
+    budget_usd:        Number(data.budget_usd       ?? 0),
+    budget_used_usd:   Number(data.budget_used_usd  ?? 0),
+  };
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+// @rule:AEG-E-016 — no AI agent may perform an irreversible action without a human approval token
+// @rule:IRR-NOAPPROVAL — core doctrine: irreversible means human-in-the-loop is mandatory
+
+export class IrrNoApprovalError extends Error {
+  readonly code = 'IRR-NOAPPROVAL';
+  readonly doctrine = 'AEG-E-016';
+
+  constructor(capability: string, reason?: string) {
+    const detail = reason ? ` (${reason})` : '';
+    super(
+      `IRR-NOAPPROVAL: capability '${capability}' requires a human approval token before execution.` +
+      ` No AI agent may perform this irreversible action without one. [AEG-E-016]${detail}`,
+    );
+    this.name = 'IrrNoApprovalError';
+  }
+}
+
+export class AegisNonceError extends Error {
+  readonly code = 'AEGIS-NONCE-REPLAY';
+
+  constructor(nonce: string) {
+    super(`AEGIS-NONCE-REPLAY: nonce '${nonce}' already consumed — approval replay rejected`);
+    this.name = 'AegisNonceError';
+  }
+}

package/src/idempotency.ts

@@ -0,0 +1,38 @@
+// @rule:AEG-HG-2B-006 — idempotency protects the operation; nonce protects the approval (separate locks)
+// Pattern: check DB for externalRef before mutating. Matching fingerprint = safe no-op. Mismatch = warn + reject.
+
+export interface IdempotencyCheckResult {
+  isDuplicate: boolean;
+  payloadMismatch: boolean;
+  safeNoOp: boolean;
+}
+
+// Functional helper: does not touch DB. Caller provides existingRecord and fingerprints.
+// When isDuplicate=true and payloadMismatch=false: safeNoOp=true — return existing record, do not re-execute.
+// When isDuplicate=true and payloadMismatch=true: safeNoOp=false — log warning; reject or escalate.
+export function checkIdempotency(
+  _externalRef: string,
+  existingRecord: unknown,
+  newFingerprint: string,
+  existingFingerprint?: string,
+): IdempotencyCheckResult {
+  const isDuplicate = existingRecord !== null && existingRecord !== undefined;
+  if (!isDuplicate) {
+    return { isDuplicate: false, payloadMismatch: false, safeNoOp: false };
+  }
+  const payloadMismatch =
+    existingFingerprint !== undefined && existingFingerprint !== newFingerprint;
+  return {
+    isDuplicate: true,
+    payloadMismatch,
+    safeNoOp: !payloadMismatch,
+  };
+}
+
+// Build a stable base64 fingerprint from an arbitrary operation payload.
+export function buildIdempotencyFingerprint(payload: Record<string, unknown>): string {
+  const sorted = Object.keys(payload)
+    .sort()
+    .reduce<Record<string, unknown>>((acc, k) => { acc[k] = payload[k]; return acc; }, {});
+  return Buffer.from(JSON.stringify(sorted)).toString('base64');
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+// @rocketlang/aegis-guard — AEGIS Guard SDK public API
+// Five Locks proved in carbonx-backend (batches 62-74). Batch 93 makes them reusable.
+
+export { IrrNoApprovalError, AegisNonceError } from './errors.js';
+
+export { type NonceStore, defaultNonceStore } from './nonce.js';
+
+export {
+  type IdempotencyCheckResult,
+  checkIdempotency,
+  buildIdempotencyFingerprint,
+} from './idempotency.js';
+
+export {
+  type AegisSenseEvent,
+  type SenseTransport,
+  configureSenseTransport,
+  emitAegisSenseEvent,
+} from './sense.js';
+
+export {
+  type QualityEvidenceInput,
+  type QualityDriftInput,
+  type HgGroup,
+  buildQualityMaskAtPromotion,
+  buildQualityDriftScore,
+  HG_REQUIRED_MASKS,
+  meetsHgQualityRequirement,
+} from './quality.js';
+
+export {
+  type ApprovalTokenPayload,
+  digestApprovalToken,
+  mintApprovalToken,
+  verifyApprovalToken,
+  verifyAndConsumeNonce,
+  verifyScopedApprovalToken,
+} from './approval-token.js';
+
+export {
+  type IssueEnvelopeParams,
+  type EnvelopeIssueResult,
+  type EnvelopeVerifyResult,
+  issueEnvelope,
+  verifyEnvelope,
+} from './envelope.js';

package/src/nonce.ts

@@ -0,0 +1,26 @@
+// @rule:AEG-HG-2B-006 — NonceStore.consumeNonce fail-closed semantics:
+//   returns true  = first use (allowed)
+//   returns false = already consumed (replay — reject)
+//   throws        = store unavailable (fails CLOSED, never open)
+// Production path: Redis SET NX EX (AEGIS PROOF at port 4850).
+// Default: in-memory (single-process only — multi-instance requires Redis).
+
+export interface NonceStore {
+  consumeNonce(nonce: string, ttlMs: number): Promise<boolean>;
+}
+
+class InMemoryNonceStore implements NonceStore {
+  private readonly used = new Map<string, number>(); // nonce → expiry timestamp
+
+  async consumeNonce(nonce: string, ttlMs: number): Promise<boolean> {
+    const now = Date.now();
+    for (const [k, exp] of this.used) {
+      if (now > exp) this.used.delete(k);
+    }
+    if (this.used.has(nonce)) return false;
+    this.used.set(nonce, now + ttlMs);
+    return true;
+  }
+}
+
+export const defaultNonceStore: NonceStore = new InMemoryNonceStore();

package/src/quality.ts

@@ -0,0 +1,80 @@
+// @rule:AEG-Q-001 — quality_mask_at_promotion: bits 0-11, point-in-time at promotion, immutable after
+// @rule:AEG-Q-002 — quality_drift_score: bits 12-15, longitudinal, post-promotion only
+// @rule:AEG-Q-003 — bits 12-15 must NEVER be set in quality_mask_at_promotion
+
+export interface QualityEvidenceInput {
+  typecheck_passed?: boolean;           // bit 0  — Q-001
+  tests_passed?: boolean;               // bit 1  — Q-002
+  lint_passed?: boolean;                // bit 2  — Q-003
+  no_unrelated_diff?: boolean;          // bit 3  — Q-004
+  migration_verified?: boolean;         // bit 4  — Q-005
+  rollback_tested?: boolean;            // bit 5  — Q-006
+  dependency_checked?: boolean;         // bit 6  — Q-007
+  codex_updated?: boolean;              // bit 7  — Q-008
+  audit_artifact_produced?: boolean;    // bit 8  — Q-009
+  scope_confirmed?: boolean;            // bit 9  — Q-010
+  no_secrets_exposed?: boolean;         // bit 10 — Q-011
+  human_reviewed?: boolean;             // bit 11 — Q-012
+}
+
+const PROMOTION_BIT_MAP: Array<[keyof QualityEvidenceInput, number]> = [
+  ['typecheck_passed',        0],
+  ['tests_passed',            1],
+  ['lint_passed',             2],
+  ['no_unrelated_diff',       3],
+  ['migration_verified',      4],
+  ['rollback_tested',         5],
+  ['dependency_checked',      6],
+  ['codex_updated',           7],
+  ['audit_artifact_produced', 8],
+  ['scope_confirmed',         9],
+  ['no_secrets_exposed',      10],
+  ['human_reviewed',          11],
+];
+
+// @rule:AEG-Q-003 — bits 12-15 are never touched by this function (point-in-time only)
+export function buildQualityMaskAtPromotion(evidence: QualityEvidenceInput): number {
+  let mask = 0;
+  for (const [field, bit] of PROMOTION_BIT_MAP) {
+    if (evidence[field] === true) mask |= (1 << bit);
+  }
+  return mask;
+}
+
+export interface QualityDriftInput {
+  idempotency_evidenced?: boolean;      // bit 12 — Q-013
+  observability_evidenced?: boolean;    // bit 13 — Q-014
+  regression_suite_pass?: boolean;      // bit 14 — Q-015
+  production_fire_zero?: boolean;       // bit 15 — Q-016
+}
+
+const DRIFT_BIT_MAP: Array<[keyof QualityDriftInput, number]> = [
+  ['idempotency_evidenced',   12],
+  ['observability_evidenced', 13],
+  ['regression_suite_pass',   14],
+  ['production_fire_zero',    15],
+];
+
+// @rule:AEG-Q-002 — drift bits 12-15 only; never OR'd with promotion mask into a single field
+export function buildQualityDriftScore(drift: QualityDriftInput): number {
+  let score = 0;
+  for (const [field, bit] of DRIFT_BIT_MAP) {
+    if (drift[field] === true) score |= (1 << bit);
+  }
+  return score;
+}
+
+// HG group minimum quality mask requirements (promotion bits 0-11 only)
+export const HG_REQUIRED_MASKS = {
+  'HG-1':            0x0302,
+  'HG-2A':           0x0B83,
+  'HG-2B':           0x0FAB,
+  'HG-2B-financial': 0x0FFF,
+} as const;
+
+export type HgGroup = keyof typeof HG_REQUIRED_MASKS;
+
+export function meetsHgQualityRequirement(hgGroup: HgGroup, qualityMask: number): boolean {
+  const required = HG_REQUIRED_MASKS[hgGroup];
+  return (qualityMask & required) === required;
+}

package/src/sense.ts

@@ -0,0 +1,38 @@
+// @rule:CA-003 — SENSE events carry before_snapshot, after_snapshot, and delta
+// @rule:AEG-HG-2B-003 — boundary-crossing irreversible events must emit to event bus
+// @rule:AEG-HG-2B-004 — gate_phase tags event to soak vs live phase
+// @rule:AEG-HG-2B-005 — approval_token_ref must be a digest (digestApprovalToken), never raw token
+
+export interface AegisSenseEvent {
+  event_type: string;
+  service_id: string;
+  capability: string;
+  operation: string;
+  before_snapshot: Record<string, unknown>;
+  after_snapshot: Record<string, unknown>;
+  delta: Record<string, unknown>;
+  emitted_at: string;
+  irreversible: boolean;
+  correlation_id: string;
+  approval_token_ref?: string;
+  idempotency_key?: string;
+  gate_phase?: string;
+}
+
+export type SenseTransport = (event: AegisSenseEvent) => void;
+
+function defaultJsonTransport(event: AegisSenseEvent): void {
+  process.stdout.write(JSON.stringify({ aegis_sense: true, ...event }) + '\n');
+}
+
+let _transport: SenseTransport = defaultJsonTransport;
+
+export function configureSenseTransport(transport: SenseTransport): void {
+  _transport = transport;
+}
+
+// @rule:CA-003 — all three snapshot fields are required by the type; callers must supply them.
+// approval_token_ref, if present, must already be the output of digestApprovalToken (AEG-HG-2B-005).
+export function emitAegisSenseEvent(event: AegisSenseEvent): void {
+  _transport(event);
+}