@ai-sdlc/orchestrator 0.10.0 → 0.13.0

package/dist/signal-ingestion/adapters/manual.d.ts

@@ -0,0 +1,78 @@
+import type { RawSignal, SignalSourceAdapter } from '../types.js';
+/**
+ * RFC-0030 OQ-13.4 v0.3 re-walkthrough default cap. 10 manual signals per
+ * operator per UTC day. Reasoning: a single operator processing >10
+ * high-signal conversations per day for the framework specifically is
+ * exceptional; 10/day allows ~50/week (sales-team conference-week scenarios);
+ * per-org override via `manualEntry.dailyCapPerOperator` for genuinely
+ * high-throughput contexts. Anti-gaming guardrail: makes sustained gaming
+ * require sustained effort while not blocking legitimate use.
+ */
+export declare const DEFAULT_MANUAL_DAILY_CAP_PER_OPERATOR = 10;
+export type ManualSignalInput = Omit<RawSignal, 'attestedAt'> & {
+    attestedAt?: Date;
+};
+export interface ManualSignalSourceAdapterOptions {
+    /**
+     * Per-operator daily cap (UTC day buckets). When exceeded, `addSignal`
+     * raises `ManualSignalRateLimitExceeded` so the registry can surface
+     * `Decision: manual-signal-rate-limit-exceeded`. Defaults to
+     * `DEFAULT_MANUAL_DAILY_CAP_PER_OPERATOR` (10). Setting to `0` or a negative
+     * value DISABLES rate limiting (operator opt-out).
+     */
+    dailyCapPerOperator?: number;
+    /**
+     * Seed entries pre-populating the adapter. Useful for tests; production
+     * adapters typically construct empty then `addSignal()` per CLI submit.
+     */
+    initialSignals?: ManualSignalInput[];
+}
+export declare class ManualSignalSourceAdapter implements SignalSourceAdapter {
+    readonly name = "signal-source-manual";
+    readonly defaultTier = 1;
+    /** Manual entry never requires OAuth (no upstream service). */
+    readonly requiresOAuth = false;
+    private readonly signals;
+    private readonly dailyCapPerOperator;
+    /**
+     * Per-operator UTC-day bucket counter:
+     *   key = `${attestedBy}|${YYYY-MM-DD}` (UTC date)
+     *   val = count of manual signals accepted in that bucket
+     *
+     * Rebuilt lazily — addSignal increments + reads from this map; the bucket
+     * key derivation uses the signal's `attestedAt` (auto-filled to `now` when
+     * omitted, so the count always lands in the correct UTC day).
+     */
+    private readonly perOperatorPerDayCount;
+    constructor(initialSignalsOrOptions?: ManualSignalInput[] | ManualSignalSourceAdapterOptions);
+    /** Effective per-operator daily cap (post-defaulting). Test helper. */
+    get effectiveDailyCap(): number;
+    isAvailable(): Promise<boolean>;
+    /**
+     * Add a manual signal with attestation + rate-limit enforcement.
+     *
+     * Order of validation:
+     *   1. `attestedBy` required → `ManualSignalIncomplete` (preserved from v0.2).
+     *   2. `attestedAt` defaulted to `now`.
+     *   3. Per-operator UTC-day cap → `ManualSignalRateLimitExceeded` when
+     *      `count(attestedBy, utcDate(attestedAt)) >= dailyCapPerOperator`.
+     *      (Skipped when `dailyCapPerOperator <= 0`.)
+     *
+     * Returns the persisted RawSignal (with `attestedAt` filled + `evidenceUrl`
+     * preserved verbatim) when accepted.
+     */
+    addSignal(input: ManualSignalInput, now?: Date): RawSignal;
+    fetchSignals(since: Date): Promise<RawSignal[]>;
+    /**
+     * Test helper: current per-operator UTC-day count for the given attestedBy.
+     * Exposed so unit tests can assert rate-limit bookkeeping without reaching
+     * into the private map.
+     */
+    countForOperatorOnDate(attestedBy: string, utcDateIso: string): number;
+}
+/**
+ * UTC date key in `YYYY-MM-DD` form. Hoisted so the manual-share metric
+ * helper (see `manual-share-metric.ts`) can use the same bucketing rule.
+ */
+export declare function utcDateKey(d: Date): string;
+//# sourceMappingURL=manual.d.ts.map

package/dist/signal-ingestion/adapters/manual.js

@@ -0,0 +1,112 @@
+import { ManualSignalIncomplete, ManualSignalRateLimitExceeded } from '../errors.js';
+/**
+ * RFC-0030 OQ-13.4 v0.3 re-walkthrough default cap. 10 manual signals per
+ * operator per UTC day. Reasoning: a single operator processing >10
+ * high-signal conversations per day for the framework specifically is
+ * exceptional; 10/day allows ~50/week (sales-team conference-week scenarios);
+ * per-org override via `manualEntry.dailyCapPerOperator` for genuinely
+ * high-throughput contexts. Anti-gaming guardrail: makes sustained gaming
+ * require sustained effort while not blocking legitimate use.
+ */
+export const DEFAULT_MANUAL_DAILY_CAP_PER_OPERATOR = 10;
+export class ManualSignalSourceAdapter {
+    name = 'signal-source-manual';
+    defaultTier = 1;
+    /** Manual entry never requires OAuth (no upstream service). */
+    requiresOAuth = false;
+    signals = [];
+    dailyCapPerOperator;
+    /**
+     * Per-operator UTC-day bucket counter:
+     *   key = `${attestedBy}|${YYYY-MM-DD}` (UTC date)
+     *   val = count of manual signals accepted in that bucket
+     *
+     * Rebuilt lazily — addSignal increments + reads from this map; the bucket
+     * key derivation uses the signal's `attestedAt` (auto-filled to `now` when
+     * omitted, so the count always lands in the correct UTC day).
+     */
+    perOperatorPerDayCount = new Map();
+    constructor(initialSignalsOrOptions = []) {
+        let initial;
+        if (Array.isArray(initialSignalsOrOptions)) {
+            // Legacy ctor signature: `new ManualSignalSourceAdapter([...])`
+            initial = initialSignalsOrOptions;
+            this.dailyCapPerOperator = DEFAULT_MANUAL_DAILY_CAP_PER_OPERATOR;
+        }
+        else {
+            initial = initialSignalsOrOptions.initialSignals ?? [];
+            this.dailyCapPerOperator =
+                initialSignalsOrOptions.dailyCapPerOperator ?? DEFAULT_MANUAL_DAILY_CAP_PER_OPERATOR;
+        }
+        for (const signal of initial)
+            this.addSignal(signal);
+    }
+    /** Effective per-operator daily cap (post-defaulting). Test helper. */
+    get effectiveDailyCap() {
+        return this.dailyCapPerOperator;
+    }
+    async isAvailable() {
+        return true;
+    }
+    /**
+     * Add a manual signal with attestation + rate-limit enforcement.
+     *
+     * Order of validation:
+     *   1. `attestedBy` required → `ManualSignalIncomplete` (preserved from v0.2).
+     *   2. `attestedAt` defaulted to `now`.
+     *   3. Per-operator UTC-day cap → `ManualSignalRateLimitExceeded` when
+     *      `count(attestedBy, utcDate(attestedAt)) >= dailyCapPerOperator`.
+     *      (Skipped when `dailyCapPerOperator <= 0`.)
+     *
+     * Returns the persisted RawSignal (with `attestedAt` filled + `evidenceUrl`
+     * preserved verbatim) when accepted.
+     */
+    addSignal(input, now = new Date()) {
+        if (!input.attestedBy) {
+            throw new ManualSignalIncomplete(input.sourceId);
+        }
+        const attestedAt = input.attestedAt ?? now;
+        // Rate-limit bucket keys MUST use wall-clock `now`, not caller-supplied
+        // `attestedAt`. A spoofed attestedAt (e.g. `new Date('2099-01-01')`)
+        // would otherwise create a fresh per-day bucket on each submit and
+        // bypass the daily cap entirely. The persisted attestedAt remains
+        // caller-supplied for audit fidelity (OQ-13.4 v0.3 anti-gaming fix).
+        const utcDate = utcDateKey(now);
+        const bucketKey = `${input.attestedBy}|${utcDate}`;
+        if (this.dailyCapPerOperator > 0) {
+            const currentCount = this.perOperatorPerDayCount.get(bucketKey) ?? 0;
+            if (currentCount >= this.dailyCapPerOperator) {
+                throw new ManualSignalRateLimitExceeded(input.attestedBy, this.dailyCapPerOperator, utcDate, input.sourceId);
+            }
+            this.perOperatorPerDayCount.set(bucketKey, currentCount + 1);
+        }
+        const signal = {
+            ...input,
+            attestedAt,
+        };
+        this.signals.push(signal);
+        return signal;
+    }
+    async fetchSignals(since) {
+        return this.signals.filter((signal) => signal.sourceTimestamp >= since);
+    }
+    /**
+     * Test helper: current per-operator UTC-day count for the given attestedBy.
+     * Exposed so unit tests can assert rate-limit bookkeeping without reaching
+     * into the private map.
+     */
+    countForOperatorOnDate(attestedBy, utcDateIso) {
+        return this.perOperatorPerDayCount.get(`${attestedBy}|${utcDateIso}`) ?? 0;
+    }
+}
+/**
+ * UTC date key in `YYYY-MM-DD` form. Hoisted so the manual-share metric
+ * helper (see `manual-share-metric.ts`) can use the same bucketing rule.
+ */
+export function utcDateKey(d) {
+    const y = d.getUTCFullYear();
+    const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+//# sourceMappingURL=manual.js.map

package/dist/signal-ingestion/adapters/support-ticket.d.ts

@@ -0,0 +1,47 @@
+import type { RawSignal, SignalSourceAdapter } from '../types.js';
+/**
+ * Default env var holding the Zendesk personal access token (PAT) per
+ * RFC-0030 OQ-13.1 v0.3 re-walkthrough. Env-var-based credential model;
+ * OAuth-scoped Zendesk integration deferred to the credential-management RFC.
+ */
+export declare const DEFAULT_SUPPORT_TICKET_ENV_VAR = "SIGNAL_ZENDESK_PAT";
+export interface SupportTicketAdapterOptions {
+    signals?: RawSignal[];
+    available?: boolean;
+    /**
+     * Legacy test override (pre-OQ-13.1 v0.3): emits the collapsed
+     * `adapter-credential-invalid` Decision. Preserved for backward-compat.
+     * New tests should use `credentialNotConfigured` or `credentialRejected`.
+     */
+    credentialInvalid?: boolean;
+    /** RFC-0030 OQ-13.1 v0.3: env-var missing test override. */
+    credentialNotConfigured?: boolean;
+    /** RFC-0030 OQ-13.1 v0.3: env-var present but upstream rejected test override. */
+    credentialRejected?: boolean;
+    /** Override the env var name (defaults to `SIGNAL_ZENDESK_PAT`). */
+    envVarName?: string;
+    /** Optional explicit env accessor (test seam). Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * When `true`, the adapter probes its env var as part of availability /
+     * fetchSignals. Defaults to `false` so the legacy in-memory test usage
+     * (passing `signals: [...]` without env-var setup) continues to work.
+     *
+     * v1-shipping deployments should set `probeEnvVar: true` to opt in to the
+     * OQ-13.1 v0.3 dual-Decision routing.
+     */
+    probeEnvVar?: boolean;
+}
+export declare class SupportTicketSignalSourceAdapter implements SignalSourceAdapter {
+    private readonly options;
+    readonly name = "signal-source-support-ticket";
+    readonly defaultTier = 1;
+    /** OAuth NOT required for the v1 Zendesk PAT credential model. */
+    readonly requiresOAuth = false;
+    constructor(options?: SupportTicketAdapterOptions);
+    /** Resolve the env var name for this adapter. */
+    get envVarName(): string;
+    isAvailable(): Promise<boolean>;
+    fetchSignals(since: Date): Promise<RawSignal[]>;
+}
+//# sourceMappingURL=support-ticket.d.ts.map

package/dist/signal-ingestion/adapters/support-ticket.js

@@ -0,0 +1,51 @@
+import { AdapterCredentialInvalid, AdapterCredentialNotConfigured, AdapterCredentialRejected, } from '../errors.js';
+/**
+ * Default env var holding the Zendesk personal access token (PAT) per
+ * RFC-0030 OQ-13.1 v0.3 re-walkthrough. Env-var-based credential model;
+ * OAuth-scoped Zendesk integration deferred to the credential-management RFC.
+ */
+export const DEFAULT_SUPPORT_TICKET_ENV_VAR = 'SIGNAL_ZENDESK_PAT';
+export class SupportTicketSignalSourceAdapter {
+    options;
+    name = 'signal-source-support-ticket';
+    defaultTier = 1;
+    /** OAuth NOT required for the v1 Zendesk PAT credential model. */
+    requiresOAuth = false;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Resolve the env var name for this adapter. */
+    get envVarName() {
+        return this.options.envVarName ?? DEFAULT_SUPPORT_TICKET_ENV_VAR;
+    }
+    async isAvailable() {
+        if (this.options.available !== undefined)
+            return this.options.available;
+        if (this.options.probeEnvVar) {
+            const env = this.options.env ?? process.env;
+            const v = env[this.envVarName];
+            return typeof v === 'string' && v.trim().length > 0;
+        }
+        return true;
+    }
+    async fetchSignals(since) {
+        if (this.options.credentialNotConfigured) {
+            throw new AdapterCredentialNotConfigured(this.name, this.envVarName);
+        }
+        if (this.options.credentialRejected) {
+            throw new AdapterCredentialRejected(this.name);
+        }
+        if (this.options.credentialInvalid) {
+            throw new AdapterCredentialInvalid(this.name);
+        }
+        if (this.options.probeEnvVar && this.options.available === undefined) {
+            const env = this.options.env ?? process.env;
+            const v = env[this.envVarName];
+            if (!(typeof v === 'string' && v.trim().length > 0)) {
+                throw new AdapterCredentialNotConfigured(this.name, this.envVarName);
+            }
+        }
+        return (this.options.signals ?? []).filter((signal) => signal.sourceTimestamp >= since);
+    }
+}
+//# sourceMappingURL=support-ticket.js.map

package/dist/signal-ingestion/classifier.d.ts

@@ -0,0 +1,205 @@
+/**
+ * RFC-0030 Phase 2 — Signal classifier.
+ *
+ * Classifies raw signals on three deterministic axes and applies the
+ * English-only language gate (OQ-13.2 resolution):
+ *
+ *   1. **Tier** — enterprise / mid / smb / free / churned (metadata-driven).
+ *      Inference order: adapter-provided `customerTier` → customerId lookup →
+ *      adapter's `defaultTier` (mapped to smb for Tier 1, free for Tier 2).
+ *
+ *   2. **ICP resonance** — strong / partial / weak (BM25 default; embedding
+ *      when RFC-0019 adapter is configured — currently always BM25 in v1).
+ *      For v1 the classifier receives an explicit `icpSegments` list from the
+ *      caller. BM25 matching measures how closely the signal payload matches
+ *      the declared ICP segments.
+ *
+ *   3. **Recency decay** — exponential decay: exp(-age_days × ln(2) / half_life).
+ *      Applied at scoring time so the pipeline doesn't need to re-compute as
+ *      time passes (age is passed as input). Half-life is read from config
+ *      (default 30 days).
+ *
+ * **Language gate** (OQ-13.2 v0.3 re-walkthrough): non-accepted-language signal
+ * payloads are detected via the `franc` library (deterministic; <10ms per
+ * signal; JS-native; MIT-licensed; 95%+ accuracy on text >50 chars; returns
+ * ISO 639-3 codes). Signals in unsupported languages are dropped and logged as
+ * `Decision: signal-language-unsupported`. Per-org `acceptedLanguages` config
+ * is respected (default `['en']`); multi-language opt-in (e.g. `['en', 'fr',
+ * 'es']`) accepts those languages knowingly — adopters take on documented BM25
+ * quality degradation (~15-30% precision drop without per-language stopwords)
+ * in exchange for non-English signal coverage.
+ *
+ * All multipliers and weights are read from `SignalIngestionConfig`; they are
+ * NOT hardcoded, satisfying AC #6.
+ *
+ * @module signal-ingestion/classifier
+ */
+import type { CustomerTier, RawSignal, SignalTier } from './types.js';
+import type { SignalIngestionConfig, TierMultipliers, IcpResonanceWeights } from './config.js';
+export type ICPResonance = 'strong' | 'partial' | 'weak';
+/** The result of classifying a single raw signal on all three axes. */
+export interface ClassifiedSignal {
+    /** Original signal, unmodified. */
+    signal: RawSignal;
+    /** Resolved customer tier (enterprise / mid / smb / free / churned). */
+    customerTier: CustomerTier;
+    /** ICP resonance level. */
+    icpResonance: ICPResonance;
+    /**
+     * Recency decay factor in [0, 1].
+     * 1.0 = fresh signal; approaches 0 for very old signals.
+     * Computed at classification time using the provided `asOf` date.
+     */
+    recencyDecay: number;
+    /**
+     * Tier multiplier looked up from config for this signal's customerTier.
+     * Convenience field — callers do NOT need to re-read the config.
+     */
+    tierMultiplier: number;
+    /**
+     * ICP resonance weight looked up from config.
+     * Convenience field.
+     */
+    icpResonanceWeight: number;
+    /**
+     * Signal-level base weight.
+     *   - Tier 1 sources: 1.0
+     *   - Tier 2 sources: 0.3 in Phase 2 (significance-threshold evaluation
+     *     is Phase 4's job; Phase 4 will downgrade to 0.0 for Tier 2 sources
+     *     below threshold, excluding them from D1 scoring).
+     * Phase 4/5 consumers MUST NOT rely on `baseWeight === 0` to detect
+     * exclusions until Phase 4 ships — Phase 2 never emits 0.0.
+     */
+    baseWeight: number;
+}
+/** Emitted when a signal is dropped for language reasons (RFC-0030 OQ-13.2 v0.3). */
+export interface SignalLanguageUnsupportedDecision {
+    type: 'Decision';
+    decision: 'signal-language-unsupported';
+    sourceId: string;
+    /**
+     * Detected language as ISO 639-3 three-letter code (e.g. `'cmn'`, `'fra'`,
+     * `'spa'`, `'eng'`). `'und'` when text was too short or no script matched.
+     * For backwards compatibility with v0.2 dashboards reading `detectedScript`,
+     * a coarse script family hint (`'cjk'`, `'cyrillic'`, `'arabic'`, `'latin'`)
+     * may still be derivable from the language code via the franc data tables.
+     */
+    detectedLanguage: string;
+    /**
+     * @deprecated since v0.3 — use `detectedLanguage`. Retained for one release
+     * window so downstream consumers (TUI, runbook examples) can migrate.
+     * Populated with a coarse script-family hint derived from `detectedLanguage`
+     * (`'cjk'`, `'cyrillic'`, `'arabic'`, `'hebrew'`, `'devanagari'`, `'thai'`,
+     * `'greek'`, `'armenian'`, `'georgian'`, `'latin'`, or `'unknown'`).
+     */
+    detectedScript: string;
+    acceptedLanguages: string[];
+    message: string;
+}
+/** Result of classifying a batch of signals. */
+export interface ClassificationResult {
+    /** Successfully classified signals. */
+    classified: ClassifiedSignal[];
+    /**
+     * Signals dropped for language reasons, emitted as Decision records per
+     * RFC-0030 OQ-13.2 resolution.
+     */
+    languageDecisions: SignalLanguageUnsupportedDecision[];
+}
+/**
+ * Optional customer-tier registry for resolving tier from `customerId`.
+ * Adopters can provide their own implementation; the pipeline falls back
+ * to adapter defaults when no registry is configured or when the
+ * `customerId` is not found.
+ */
+export interface CustomerTierRegistry {
+    resolve(customerId: string): CustomerTier | undefined;
+}
+export interface ClassifySignalsOptions {
+    /**
+     * Point in time used to compute signal ages.
+     * Defaults to `new Date()` when not provided.
+     */
+    asOf?: Date;
+    /**
+     * Resolved signal ingestion configuration. Defaults to the built-in
+     * default config when not provided.
+     */
+    config?: SignalIngestionConfig;
+    /**
+     * Source adapter tier used for base-weight assignment when the signal does
+     * not carry `customerTier`. Keyed by adapter name.
+     *
+     * When not provided, base weight defaults to 1.0 (Tier 1 bias).
+     */
+    adapterTiers?: Map<string, SignalTier>;
+    /**
+     * ICP segment descriptors — the product's declared ideal customer profile.
+     * Each entry is a short phrase describing one ICP dimension
+     * (e.g. "B2B SaaS startup", "engineering team", "productivity tooling").
+     *
+     * BM25 similarity between the signal payload and these segments determines
+     * ICP resonance. When empty, all signals are classified as `partial`.
+     */
+    icpSegments?: string[];
+    /**
+     * Optional customer-tier registry for `customerId` lookup (tier inference
+     * order step 2). When absent, step 2 is skipped.
+     */
+    tierRegistry?: CustomerTierRegistry;
+}
+/**
+ * Classify a batch of raw signals.
+ *
+ * Per RFC-0030 §6 inference order for tier:
+ *   1. `signal.customerTier` (adapter-provided structured field)
+ *   2. `tierRegistry.resolve(signal.customerId)` (registry lookup)
+ *   3. Adapter `defaultTier` (mapped: Tier 1 → smb, Tier 2 → free)
+ *
+ * Per RFC-0030 §13.2: non-accepted-language signals are dropped and
+ * returned in `languageDecisions`.
+ */
+export declare function classifySignals(signals: RawSignal[], options?: ClassifySignalsOptions): ClassificationResult;
+/**
+ * Resolve customer tier per RFC-0030 §6.1 inference order:
+ *   1. `signal.customerTier`
+ *   2. `tierRegistry.resolve(signal.customerId)`
+ *   3. Adapter defaultTier → smb (Tier 1) or free (Tier 2)
+ */
+export declare function resolveCustomerTier(signal: RawSignal, tierRegistry?: CustomerTierRegistry, adapterTiers?: Map<string, SignalTier>): CustomerTier;
+/**
+ * Classify ICP resonance for a signal payload against the declared ICP
+ * segment descriptors using BM25 similarity.
+ *
+ * When `icpSegments` is empty, returns `partial` (no basis for strong/weak).
+ *
+ * BM25 parameters (k1=1.5, b=0.75) are standard.
+ * Score mapping:
+ *   - ≥ 0.5  → strong
+ *   - ≥ 0.15 → partial
+ *   - < 0.15 → weak
+ */
+export declare function resolveIcpResonance(payload: string, icpSegments: string[]): ICPResonance;
+/** Tokenize a string to lowercase alphanumeric tokens, minimum length 2. */
+export declare function tokenize(text: string): string[];
+/**
+ * Compute exponential recency decay for a signal.
+ *
+ * `decay = exp(-age_days * ln(2) / halfLifeDays)`
+ *
+ * At age = halfLifeDays, decay = 0.5.
+ * At age = 0, decay = 1.0.
+ * Future-dated signals (age < 0) clamp to 1.0.
+ */
+export declare function computeRecencyDecay(sourceTimestamp: Date, asOf: Date, halfLifeDays: number): number;
+/**
+ * Compute the composite signal weight from a `ClassifiedSignal`.
+ *
+ * `weight = baseWeight × tierMultiplier × icpResonanceWeight × recencyDecay`
+ *
+ * Note: SA resonance filter (RFC-0030 §9) is applied at the cluster level in
+ * Phase 5, not at the signal level here.
+ */
+export declare function computeSignalWeight(classified: ClassifiedSignal): number;
+export type { TierMultipliers, IcpResonanceWeights };
+//# sourceMappingURL=classifier.d.ts.map