license-policy-config.yaml

lemetry, evaluates policies, and triggers lifecycle actions. The system must operate across heterogeneous license types without relying on vendor-specific APIs.

Architecture Decisions and Rationale

1. License Registry: Centralized source of truth mapping vendor contracts, entitlement counts, renewal dates, and classification tags (per-seat, usage-based, tiered, perpetual). Stored in a relational database with versioned snapshots for audit trails.
2. Usage Telemetry Collector: Lightweight agents or SDK wrappers that capture activity signals: IDE heartbeats, API call volumes, concurrent session counts, feature flag activations, and CI/CD pipeline invocations. Data is normalized to a unified schema before ingestion.
3. Policy Engine: Rule-based evaluator that maps telemetry thresholds to lifecycle actions. Supports time-based decay, utilization percentage triggers, and grace periods. Decoupled from provisioning systems to allow safe testing.
4. Orchestration Layer: API gateway that communicates with IDPs, procurement platforms, and vendor management portals. Handles deprovisioning, downgrading, and renewal alerts with human-in-the-loop approval gates.

The architecture avoids vendor lock-in by abstracting license types into a common model. Usage signals are normalized rather than parsed per-vendor, enabling cross-tool optimization. Policy evaluation is stateless to support horizontal scaling and rollback.

Step-by-Step Implementation

Step 1: Model License Entitlements

Define a type-safe schema for license inventory. This enables consistent policy evaluation across heterogeneous vendors.

export interface LicenseEntitlement {
  id: string;
  vendor: string;
  type: 'per-seat' | 'usage-based' | 'tiered' | 'perpetual';
  totalCapacity: number;
  activeSeats: number;
  renewalDate: Date;
  contractId: string;
  tags: string[]; // e.g., 'ci-cd', 'ide', 'cloud-sdk'
}

export interface UsageSignal {
  licenseId: string;
  userId: string;
  timestamp: Date;
  metric: 'login' | 'api_call' | 'session_active' | 'pipeline_run';
  value: number;
}

Step 2: Collect and Aggregate Usage

Normalize telemetry from multiple sources. Batch ingestion reduces database load and enables windowed analysis.

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export async function aggregateLicenseUsage(
  licenseId: string,
  windowDays: number = 30
): Promise<{ activeUsers: number; totalSignals: number; lastActive: Date }> {
  const cutoff = new Date();
  cutoff.setDate(cutoff.getDate() - windowDays);

  const signals = await prisma.usageSignal.findMany({
    where: { licenseId, timestamp: { gte: cutoff } },
    select: { userId: true, timestamp: true },
  });

  const activeUsers = new Set(signals.map(s => s.userId)).size;
  const lastActive = signals.length > 0
    ? signals.reduce((latest, s) => s.timestamp > latest ? s.timestamp : latest, signals[0].timestamp)
    : new Date(0);

  return { activeUsers, totalSignals: signals.length, lastActive };
}

Step 3: Policy Evaluation Engine

Implement deterministic rules that map utilization to lifecycle recommendations. Policies should be versioned and auditable.

export type PolicyAction = 'retain' | 'downgrade' | 'reclaim' | 'alert_renewal';

export interface PolicyRule {
  id: string;
  licenseType: string;
  condition: (utilization: number, daysInactive: number) => boolean;
  action: PolicyAction;
  priority: number;
}

export const defaultPolicies: PolicyRule[] = [
  {
    id: 'low-utilization-reclaim',
    licenseType: 'per-seat',
    condition: (util: number, daysInactive: number) => util < 0.15 && daysInactive > 45,
    action: 'reclaim',
    priority: 10,
  },
  {
    id: 'usage-based-downgrade',
    licenseType: 'usage-based',
    condition: (util: number, daysInactive: number) => util < 0.25 && daysInactive > 30,
    action: 'downgrade',
    priority: 8,
  },
  {
    id: 'renewal-alert',
    licenseType: '*',
    condition: (_util: number, _days: number) => true, // evaluated separately by date
    action: 'alert_renewal',
    priority: 5,
  },
];

export function evaluatePolicy(
  entitlement: LicenseEntitlement,
  utilization: number,
  daysInactive: number
): PolicyAction {
  const applicable = defaultPolicies
    .filter(p => p.licenseType === entitlement.type || p.licenseType === '*')
    .sort((a, b) => b.priority - a.priority);

  const matched = applicable.find(p => p.condition(utilization, daysInactive));
  return matched?.action ?? 'retain';
}

Step 4: Orchestrate Lifecycle Actions

Decouple evaluation from execution. Use a queue-based workflow to handle approvals, vendor API calls, and audit logging.

export async function executeReclamation(
  entitlementId: string,
  action: PolicyAction,
  userId: string
): Promise<{ status: 'pending' | 'executed' | 'blocked'; reason?: string }> {
  const entitlement = await prisma.licenseEntitlement.findUnique({
    where: { id: entitlementId },
  });

  if (!entitlement) throw new Error('Entitlement not found');

  // Human-in-the-loop gate for high-impact actions
  if (action === 'reclaim' && entitlement.totalCapacity > 50) {
    await prisma.reclamationRequest.create({
      data: {
        entitlementId,
        action,
        requestedBy: userId,
        status: 'pending_approval',
        requiresManagerApproval: true,
      },
    });
    return { status: 'pending', reason: 'Capacity threshold requires approval' };
  }

  // Vendor API integration stub
  await vendorDeprovisionClient.execute(entitlement.contractId, action);

  await prisma.licenseEntitlement.update({
    where: { id: entitlementId },
    data: { activeSeats: { decrement: 1 } },
  });

  return { status: 'executed' };
}

Architecture Rationale

• Type Safety: Interfaces enforce consistent data contracts across telemetry, policy, and orchestration layers.
• Stateless Policy Evaluation: Enables A/B testing of rules, rollback on misconfigurations, and horizontal scaling.
• Approval Gates: Prevents accidental deprovisioning of critical tooling while maintaining automation velocity.
• Audit-First Design: Every state change is logged with user, timestamp, and policy trigger, satisfying compliance requirements without additional tooling.

Pitfall Guide

1. Treating All License Types as Identical

Per-seat, usage-based, and tiered licenses require fundamentally different telemetry and reclamation logic. Applying seat-based decay rules to API-call licenses triggers false reclamation. Always classify entitlements before policy evaluation.

2. Ignoring Indirect and Transitive Dependencies

Commercial SDKs often pull in licensed sub-components. Failure to map dependency trees results in hidden compliance exposure. Integrate with SBOM generators and package lock parsers to capture indirect licensing.

3. Over-Automating Without Grace Periods

Immediate reclamation on inactivity triggers developer friction and workflow disruption. Implement configurable grace windows (14–45 days) and notification sequences before execution. Automation without empathy breaks trust.

4. Misaligning Telemetry with Actual Value

Login counts or API pings do not equal productive usage. A developer may trigger a license heartbeat via background sync without active development. Correlate signals with commit activity, PR creation, or pipeline success rates to distinguish nominal vs. meaningful usage.

5. Skipping Contractual Validation Before Reclamation

Vendor agreements often include minimum term commitments, seat guarantees, or early termination fees. Automated reclamation that violates contract terms triggers penalty clauses. Cross-reference entitlements with contract clauses before executing downgrade or reclaim actions.

6. Centralizing Without Cross-Team Visibility

Platform engineering teams that hoard license data create bottlenecks. Decentralized ownership with centralized telemetry enables faster reclamation. Expose usage dashboards to team leads and allow delegated reclamation within policy bounds.

7. Neglecting Renewal Leverage Optimization

License optimization isn't just about cutting waste; it's about renegotiating smarter. Historical usage data provides concrete leverage for volume discounts, tier adjustments, or contract restructuring. Failing to feed telemetry into procurement cycles leaves negotiated savings on the table.

Best Practices from Production

• Phase rollout: Start with low-risk tools (IDE plugins, documentation platforms) before targeting core CI/CD or cloud SDKs.
• Implement policy versioning: Treat license rules like infrastructure code. Review quarterly, rollback on incidents.
• Maintain human oversight: Automated reclamation should require explicit opt-out for critical path tools.
• Integrate with procurement APIs: Close the loop between usage data and contract negotiations.
• Monitor carbon and cost correlation: Idle licenses often provision background telemetry infrastructure. Tracking both aligns cost optimization with sustainability targets.

Production Bundle

Action Checklist

• Inventory all commercial licenses: Export contracts, seat counts, renewal dates, and vendor terms into a centralized registry.
• Classify license types: Tag each entitlement as per-seat, usage-based, tiered, or perpetual to enable accurate policy mapping.
• Deploy usage telemetry collectors: Integrate lightweight agents or SDK wrappers to capture login, API, session, and pipeline signals.
• Implement policy engine with approval gates: Configure utilization thresholds, grace periods, and human-in-the-loop workflows before automation.
• Connect to orchestration layer: Wire policy actions to IDP deprovisioning, procurement APIs, and audit logging systems.
• Establish quarterly policy review: Adjust thresholds based on usage drift, vendor contract changes, and team feedback.
• Feed telemetry into procurement cycles: Use historical utilization data to negotiate renewal terms, tier downgrades, or volume discounts.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small team (<50 devs), manual tracking	Centralized spreadsheet + quarterly audit	Low overhead, sufficient visibility at scale	10–15% waste reduction
Mid-size org (50–500 devs), mixed license types	Automated telemetry + policy engine with approval gates	Balances automation speed with compliance safety	20–30% waste reduction
Enterprise (500+ devs), usage-based contracts	Centralized orchestration + procurement API integration	Enables dynamic tier adjustment and contract renegotiation	25–35% waste reduction
Compliance-heavy industry (finance, healthcare)	Audit-first policy engine + human-only reclamation	Minimizes regulatory exposure while capturing idle cost	15–20% waste reduction
Startup scaling rapidly, volatile tool adoption	Lightweight collector + flexible grace periods + monthly review	Adapts to changing stack without rigid automation	10–18% waste reduction

Configuration Template

# license-policy-config.yaml
version: "1.0"
registry:
  db_connection: "${LICENSE_DB_URL}"
  sync_interval: "1h"

telemetry:
  collection_window_days: 30
  signal_types:
    - login
    - api_call
    - session_active
    - pipeline_run
  normalization:
    active_threshold: 0.15
    inactive_days: 45

policies:
  - id: "per-seat-reclaim"
    license_type: "per-seat"
    condition:
      utilization_lt: 0.15
      days_inactive_gt: 45
    action: "reclaim"
    priority: 10
    requires_approval: true
    approval_threshold_seats: 50

  - id: "usage-based-downgrade"
    license_type: "usage-based"
    condition:
      utilization_lt: 0.25
      days_inactive_gt: 30
    action: "downgrade"
    priority: 8
    requires_approval: false

  - id: "renewal-alert"
    license_type: "*"
    condition:
      days_to_renewal_lt: 60
    action: "alert_renewal"
    priority: 5
    requires_approval: false

orchestration:
  idp_deprovision_endpoint: "${IDP_API_URL}"
  procurement_sync: true
  audit_log_retention_days: 365
  human_in_the_loop: true

Quick Start Guide

1. Initialize the registry: Run npx @codcompass/license-init --db-url <your-db> to scaffold the entitlement schema and generate migration scripts.
2. Deploy telemetry collectors: Add the provided Node.js/TypeScript SDK to your CI/CD pipelines and IDE extensions. Configure signal endpoints to point to your telemetry pipeline.
3. Load policy configuration: Copy license-policy-config.yaml to your platform config directory. Adjust utilization thresholds and grace periods to match your team's workflow patterns.
4. Execute dry-run evaluation: Run npx @codcompass/license-eval --dry-run to simulate policy outcomes without triggering reclamation. Review the audit log for false positives.
5. Enable orchestration: Set human_in_the_loop: true in the config, deploy the orchestration service, and verify approval workflows in your IDP and procurement dashboards. Monitor first-cycle reclamation metrics for 14 days before adjusting thresholds.