@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/signal-ingestion/governance-events.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Signal-ingestion governance event logger (RFC-0030 §11 / AISDLC-348).
+ *
+ * Per the RFC §11 closing note: "Configuration changes require Product
+ * Lead approval (logged as governance events; not DID changes but
+ * governance-relevant)." This module ships the audit trail.
+ *
+ * Trigger surface:
+ *   - `loadSignalIngestionConfigWithGovernance()` calls
+ *     `loadSignalIngestionConfig()` then diffs the result against
+ *     `DEFAULT_SIGNAL_INGESTION_CONFIG`. When the diff is non-empty AND
+ *     a `previousConfigSnapshot` is supplied (operators tracking version
+ *     boundaries), it appends one `SignalIngestionConfigChanged` JSONL
+ *     line to the orchestrator events stream.
+ *   - Pure callers that just want the diff without the I/O can use
+ *     `computeConfigDiff()` directly.
+ *
+ * Path convention: events land at
+ * `<artifactsDir>/_orchestrator/events-YYYY-MM-DD.jsonl`, the same
+ * date-rotated file pipeline-cli's orchestrator writes to (RFC-0015
+ * Phase 4 / AISDLC-169.4). Keeping one file means
+ * `cli-status --orchestrator` + the TUI events tail surface signal-
+ * ingestion governance events alongside dispatch / completion events
+ * without per-RFC observability silos.
+ *
+ * Why a separate writer instead of importing pipeline-cli's `writeEvent()`:
+ * `orchestrator/` does not depend on `pipeline-cli/` (the dependency
+ * graph runs the other way), so a direct import would invert the layer
+ * boundary. The writer here is small enough (`appendFileSync` + mkdir +
+ * date-suffix) that duplication is the right trade vs. a circular dep.
+ *
+ * Best-effort like the orchestrator's `writeEvent()`: never throws, returns
+ * a boolean for test observability.
+ */
+import { type LoadSignalIngestionConfigOptions, type SignalIngestionConfig, type SignalIngestionConfigDeprecatedFieldDecision } from './config.js';
+/**
+ * One field that drifted between two `SignalIngestionConfig` snapshots.
+ *
+ * `path` uses dot notation (e.g. `tierMultipliers.enterprise`,
+ * `clustering.algorithm`). `previous` is the value in the baseline /
+ * previous snapshot; `current` is the value in the freshly-loaded config.
+ *
+ * Array fields (`adapters`, `acceptedLanguages`) are compared as ordered
+ * lists — order changes count as drift because the registry honours
+ * insertion order for tiebreaks.
+ */
+export interface SignalIngestionConfigChange {
+    path: string;
+    previous: unknown;
+    current: unknown;
+}
+/**
+ * Result of `computeConfigDiff(previous, current)`. `changed` is true when
+ * at least one field drifted. `changes` lists every drifted field; empty
+ * when `changed === false`.
+ */
+export interface SignalIngestionConfigDiff {
+    changed: boolean;
+    changes: SignalIngestionConfigChange[];
+}
+/**
+ * Compute the field-level diff between two `SignalIngestionConfig`
+ * snapshots. Pure / no I/O; safe to call from any context.
+ *
+ * The diff is deterministic: changes are sorted by `path` lexicographic
+ * so the same drift always produces the same `changes` array (audit
+ * stability + diff stability across operators).
+ */
+export declare function computeConfigDiff(previous: SignalIngestionConfig, current: SignalIngestionConfig): SignalIngestionConfigDiff;
+/**
+ * One JSONL line on the orchestrator events stream representing a
+ * detected configuration change. Mirrors the discriminator pattern from
+ * `pipeline-cli/src/orchestrator/events.ts`: every event carries
+ * `{ts, type, ...}`. The `type` value `SignalIngestionConfigChanged` is
+ * stable; downstream consumers (`cli-status --orchestrator`, the TUI
+ * events pane, Slack push) filter on it without coupling to per-field
+ * shape.
+ */
+export interface SignalIngestionConfigChangedEvent {
+    /** ISO-8601 timestamp set by the writer at append time. */
+    ts: string;
+    /** Discriminator — stable across the soak window + post-promotion. */
+    type: 'SignalIngestionConfigChanged';
+    /** Absolute or repo-relative path to the YAML file loaded. */
+    configPath: string;
+    /** Field-level changes detected vs the previous snapshot. */
+    changes: SignalIngestionConfigChange[];
+    /**
+     * When the previous snapshot was the framework default vs. an actual
+     * previous load. Lets dashboards distinguish "operator opted in" (first
+     * non-default load) from "operator tuned the config" (delta between
+     * two non-default loads).
+     */
+    comparedAgainst: 'defaults' | 'previous-load';
+}
+export interface WriteConfigChangeEventOpts {
+    /**
+     * Override the artifacts directory. Falls back to env `ARTIFACTS_DIR`
+     * then `<cwd>/artifacts`, matching pipeline-cli's `writeEvent()` so
+     * both writers land in the same date-rotated file.
+     */
+    artifactsDir?: string;
+    /** Override `Date.now()` for the rotation suffix + the event `ts`. */
+    now?: () => Date;
+    /**
+     * Optional warn-sink for best-effort write failures. The orchestrator
+     * passes its CLI logger; tests pass a capturing stub.
+     */
+    warn?: (msg: string) => void;
+}
+/**
+ * Append a `SignalIngestionConfigChanged` event to the orchestrator's
+ * date-rotated events file. Best-effort: returns `false` on write failure
+ * (logged via `warn`) instead of throwing.
+ */
+export declare function writeSignalIngestionConfigChangedEvent(event: SignalIngestionConfigChangedEvent, opts?: WriteConfigChangeEventOpts): boolean;
+/**
+ * Resolve the on-disk path for the date-rotated events file. Mirrors
+ * `pipeline-cli/src/orchestrator/events.ts#eventsFilePath()` so the two
+ * writers append to the same file. Exported so tests + cli-status can
+ * derive the same path without duplicating the rotation logic.
+ */
+export declare function eventsFilePath(artifactsDir: string, date?: Date): string;
+export interface LoadConfigWithGovernanceOptions extends LoadSignalIngestionConfigOptions {
+    /**
+     * Previous-load snapshot to compare against. When omitted, the diff is
+     * computed against `DEFAULT_SIGNAL_INGESTION_CONFIG` and the event's
+     * `comparedAgainst` field is set to `'defaults'`.
+     *
+     * Operators tracking version-to-version drift (e.g. a long-running
+     * orchestrator that reloads the config on a tick) pass the previous
+     * resolved config here; the event then carries `comparedAgainst:
+     * 'previous-load'` so dashboards can distinguish "first load on this
+     * project" from "operator tuned the knobs mid-run".
+     */
+    previousConfigSnapshot?: SignalIngestionConfig;
+    /** Override artifacts dir + clock — passed through to the event writer. */
+    artifactsDir?: string;
+    now?: () => Date;
+    warn?: (msg: string) => void;
+    /**
+     * When true, suppress the events.jsonl append (still computes the diff
+     * and returns it). Tests use this to assert the diff shape without
+     * touching the filesystem; production callers leave it false.
+     */
+    skipEventEmission?: boolean;
+}
+export interface LoadConfigWithGovernanceResult {
+    config: SignalIngestionConfig;
+    diff: SignalIngestionConfigDiff;
+    /** True when an event was successfully written to events.jsonl. */
+    eventWritten: boolean;
+    /** Absolute path the loader used (echoed for downstream logging). */
+    configPath: string;
+    /**
+     * Deprecation Decisions emitted during config load — e.g. legacy
+     * `sourceBaselineDriftMultiplier` translated to `zScoreThreshold`. Empty
+     * array when no legacy keys were present. Callers should pipe each into
+     * `cli-decisions add` so the operator sees the soft-deprecation window
+     * status. AISDLC-433 follow-up: governance loader now routes through
+     * `loadSignalIngestionConfigWithDeprecations` so the audit trail does
+     * NOT silently drop legacy YAML keys.
+     */
+    deprecations: SignalIngestionConfigDeprecatedFieldDecision[];
+}
+/**
+ * Load the signal-ingestion config and emit a `SignalIngestionConfigChanged`
+ * event when the loaded config differs from the comparison baseline
+ * (defaults, or `previousConfigSnapshot` when supplied).
+ *
+ * Returns `{config, diff, eventWritten, configPath}`. `eventWritten` is
+ * `false` when (a) there was no diff to report, (b) the caller passed
+ * `skipEventEmission: true`, or (c) the best-effort write threw.
+ *
+ * This is the canonical entry point for orchestrator surfaces that want
+ * the audit trail. Pure callers that just need the resolved config can
+ * keep using `loadSignalIngestionConfig()` directly — they bypass the
+ * governance layer entirely.
+ */
+export declare function loadSignalIngestionConfigWithGovernance(options?: LoadConfigWithGovernanceOptions): LoadConfigWithGovernanceResult;
+//# sourceMappingURL=governance-events.d.ts.map

package/dist/signal-ingestion/governance-events.js

@@ -0,0 +1,189 @@
+/**
+ * Signal-ingestion governance event logger (RFC-0030 §11 / AISDLC-348).
+ *
+ * Per the RFC §11 closing note: "Configuration changes require Product
+ * Lead approval (logged as governance events; not DID changes but
+ * governance-relevant)." This module ships the audit trail.
+ *
+ * Trigger surface:
+ *   - `loadSignalIngestionConfigWithGovernance()` calls
+ *     `loadSignalIngestionConfig()` then diffs the result against
+ *     `DEFAULT_SIGNAL_INGESTION_CONFIG`. When the diff is non-empty AND
+ *     a `previousConfigSnapshot` is supplied (operators tracking version
+ *     boundaries), it appends one `SignalIngestionConfigChanged` JSONL
+ *     line to the orchestrator events stream.
+ *   - Pure callers that just want the diff without the I/O can use
+ *     `computeConfigDiff()` directly.
+ *
+ * Path convention: events land at
+ * `<artifactsDir>/_orchestrator/events-YYYY-MM-DD.jsonl`, the same
+ * date-rotated file pipeline-cli's orchestrator writes to (RFC-0015
+ * Phase 4 / AISDLC-169.4). Keeping one file means
+ * `cli-status --orchestrator` + the TUI events tail surface signal-
+ * ingestion governance events alongside dispatch / completion events
+ * without per-RFC observability silos.
+ *
+ * Why a separate writer instead of importing pipeline-cli's `writeEvent()`:
+ * `orchestrator/` does not depend on `pipeline-cli/` (the dependency
+ * graph runs the other way), so a direct import would invert the layer
+ * boundary. The writer here is small enough (`appendFileSync` + mkdir +
+ * date-suffix) that duplication is the right trade vs. a circular dep.
+ *
+ * Best-effort like the orchestrator's `writeEvent()`: never throws, returns
+ * a boolean for test observability.
+ */
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DEFAULT_SIGNAL_INGESTION_CONFIG, loadSignalIngestionConfigWithDeprecations, } from './config.js';
+// ── Diff function ──────────────────────────────────────────────────────
+/**
+ * Compute the field-level diff between two `SignalIngestionConfig`
+ * snapshots. Pure / no I/O; safe to call from any context.
+ *
+ * The diff is deterministic: changes are sorted by `path` lexicographic
+ * so the same drift always produces the same `changes` array (audit
+ * stability + diff stability across operators).
+ */
+export function computeConfigDiff(previous, current) {
+    const changes = [];
+    walkAndCompare('', previous, current, changes);
+    changes.sort((a, b) => a.path.localeCompare(b.path));
+    return { changed: changes.length > 0, changes };
+}
+function walkAndCompare(prefix, prev, curr, out) {
+    // Array fields — compared as ordered list (insertion order matters).
+    if (Array.isArray(prev) || Array.isArray(curr)) {
+        if (!arraysEqual(prev, curr)) {
+            out.push({ path: prefix || '(root)', previous: prev, current: curr });
+        }
+        return;
+    }
+    // Object fields — recurse field-by-field. Take the union of keys so
+    // additions + removals both surface as drift.
+    if (isPlainObject(prev) && isPlainObject(curr)) {
+        const keys = new Set([...Object.keys(prev), ...Object.keys(curr)]);
+        for (const k of keys) {
+            const nextPrefix = prefix ? `${prefix}.${k}` : k;
+            walkAndCompare(nextPrefix, prev[k], curr[k], out);
+        }
+        return;
+    }
+    // Scalar leaf — compare via strict equality (numbers + strings +
+    // booleans are the only scalar types in the config). NaN is treated as
+    // unequal to itself, matching JavaScript's `!==` semantics; the loader
+    // rejects NaN at validation time so this branch should never fire in
+    // production but defending against it costs nothing.
+    if (prev !== curr) {
+        out.push({ path: prefix || '(root)', previous: prev, current: curr });
+    }
+}
+function arraysEqual(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Append a `SignalIngestionConfigChanged` event to the orchestrator's
+ * date-rotated events file. Best-effort: returns `false` on write failure
+ * (logged via `warn`) instead of throwing.
+ */
+export function writeSignalIngestionConfigChangedEvent(event, opts = {}) {
+    const artifactsDir = resolveArtifactsDir(opts);
+    const now = opts.now ?? (() => new Date());
+    const date = now();
+    const stamped = {
+        ...event,
+        ts: event.ts || date.toISOString(),
+    };
+    const path = eventsFilePath(artifactsDir, date);
+    const line = JSON.stringify(stamped) + '\n';
+    try {
+        if (!existsSync(dirname(path))) {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        appendFileSync(path, line, { encoding: 'utf8' });
+        return true;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        opts.warn?.(`[signal-ingestion-governance] events write failed (path=${path}): ${reason}`);
+        return false;
+    }
+}
+function resolveArtifactsDir(opts) {
+    return opts.artifactsDir ?? process.env.ARTIFACTS_DIR ?? join(process.cwd(), 'artifacts');
+}
+/**
+ * Resolve the on-disk path for the date-rotated events file. Mirrors
+ * `pipeline-cli/src/orchestrator/events.ts#eventsFilePath()` so the two
+ * writers append to the same file. Exported so tests + cli-status can
+ * derive the same path without duplicating the rotation logic.
+ */
+export function eventsFilePath(artifactsDir, date = new Date()) {
+    return join(artifactsDir, '_orchestrator', `events-${formatDate(date)}.jsonl`);
+}
+function formatDate(d) {
+    // YYYY-MM-DD in UTC — matches `pipeline-cli/src/orchestrator/events.ts`
+    // so rotation seams align across writers.
+    const yyyy = d.getUTCFullYear().toString().padStart(4, '0');
+    const mm = (d.getUTCMonth() + 1).toString().padStart(2, '0');
+    const dd = d.getUTCDate().toString().padStart(2, '0');
+    return `${yyyy}-${mm}-${dd}`;
+}
+/**
+ * Load the signal-ingestion config and emit a `SignalIngestionConfigChanged`
+ * event when the loaded config differs from the comparison baseline
+ * (defaults, or `previousConfigSnapshot` when supplied).
+ *
+ * Returns `{config, diff, eventWritten, configPath}`. `eventWritten` is
+ * `false` when (a) there was no diff to report, (b) the caller passed
+ * `skipEventEmission: true`, or (c) the best-effort write threw.
+ *
+ * This is the canonical entry point for orchestrator surfaces that want
+ * the audit trail. Pure callers that just need the resolved config can
+ * keep using `loadSignalIngestionConfig()` directly — they bypass the
+ * governance layer entirely.
+ */
+export function loadSignalIngestionConfigWithGovernance(options = {}) {
+    // Route through loadSignalIngestionConfigWithDeprecations so the
+    // canonical governance-aware loader does NOT silently drop legacy
+    // `sourceBaselineDriftMultiplier` keys (codex MAJOR on #752 — the
+    // basic loader runs resolveFloodingDetection which ignores unknown
+    // keys, breaking the one-release-window soft-translation contract).
+    const { config, deprecations } = loadSignalIngestionConfigWithDeprecations({
+        projectRoot: options.projectRoot,
+        configPath: options.configPath,
+    });
+    const previous = options.previousConfigSnapshot ?? DEFAULT_SIGNAL_INGESTION_CONFIG;
+    const comparedAgainst = options.previousConfigSnapshot ? 'previous-load' : 'defaults';
+    const diff = computeConfigDiff(previous, config);
+    const configPath = options.configPath ??
+        (options.projectRoot
+            ? join(options.projectRoot, '.ai-sdlc', 'signal-ingestion.yaml')
+            : join(process.cwd(), '.ai-sdlc', 'signal-ingestion.yaml'));
+    let eventWritten = false;
+    if (diff.changed && !options.skipEventEmission) {
+        eventWritten = writeSignalIngestionConfigChangedEvent({
+            ts: '',
+            type: 'SignalIngestionConfigChanged',
+            configPath,
+            changes: diff.changes,
+            comparedAgainst,
+        }, {
+            artifactsDir: options.artifactsDir,
+            now: options.now,
+            warn: options.warn,
+        });
+    }
+    return { config, diff, eventWritten, configPath, deprecations };
+}
+//# sourceMappingURL=governance-events.js.map

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

@@ -0,0 +1,35 @@
+export { type AdapterCredentialInvalidDecision, type AdapterCredentialNotConfiguredDecision, type AdapterCredentialRejectedDecision, type AdapterRequiresCredentialMgmtRfcDecision, type CustomerTier, type ManualSignalIncompleteDecision, type ManualSignalRateLimitExceededDecision, type ManualSignalShareElevatedDecision, type RawSignal, type SignalFetchResult, type SignalResidencyViolationDecision, type SignalSourceAdapter, type SignalSourceName, type SignalTier, } from './types.js';
+export { AdapterCredentialInvalid, AdapterCredentialNotConfigured, AdapterCredentialRejected, AdapterRequiresCredentialMgmtRfc, ManualSignalIncomplete, ManualSignalRateLimitExceeded, SignalSourceUnavailable, UnknownSignalSource, } from './errors.js';
+export { SignalSourceRegistry, fetchSignalsFromAvailableAdapters, getSignalSourceAdapter, } from './registry.js';
+export { SupportTicketSignalSourceAdapter, DEFAULT_SUPPORT_TICKET_ENV_VAR, type SupportTicketAdapterOptions, } from './adapters/support-ticket.js';
+export { CommunityThreadSignalSourceAdapter, DEFAULT_COMMUNITY_THREAD_ENV_VAR, type CommunityThreadAdapterOptions, } from './adapters/community-thread.js';
+export { InAppFeedbackSignalSourceAdapter, DEFAULT_IN_APP_FEEDBACK_ENV_VAR, type InAppFeedbackAdapterOptions, } from './adapters/in-app-feedback.js';
+export { ManualSignalSourceAdapter, DEFAULT_MANUAL_DAILY_CAP_PER_OPERATOR, utcDateKey, type ManualSignalInput, type ManualSignalSourceAdapterOptions, } from './adapters/manual.js';
+export { computeManualShareMetric, defaultIsManualSignal, DEFAULT_MANUAL_SHARE_MIN_POPULATION, DEFAULT_MANUAL_SHARE_WARNING_THRESHOLD, DEFAULT_MANUAL_SHARE_WINDOW_DAYS, type ManualShareMetricOptions, type ManualShareMetricResult, } from './manual-share-metric.js';
+export { classifySignals, computeRecencyDecay, computeSignalWeight, resolveCustomerTier, resolveIcpResonance, tokenize, type ClassificationResult, type ClassifiedSignal, type ClassifySignalsOptions, type CustomerTierRegistry, type ICPResonance, type SignalLanguageUnsupportedDecision, } from './classifier.js';
+export { loadSignalIngestionConfig, loadSignalIngestionConfigWithDeprecations, DEFAULT_SIGNAL_INGESTION_CONFIG, DEFAULT_SIGNAL_INGESTION_CONFIG_PATH, SignalIngestionConfigError, type ClusteringConfig, type D1CompositionWeights, type FloodingConfig, type FloodingDetectionConfig, type FloodingQuarantineConfig, type IcpResonanceWeights, type LanguageDetectionConfig, type LoadSignalIngestionConfigOptions, type LoadSignalIngestionConfigWithDeprecationsResult, type ManualEntryConfig, type ManualEntryQualityMetricConfig, type ResidencyEnforcementConfig, type SaResonanceThresholds, type SignalIngestionConfig, type SignalIngestionConfigDeprecatedFieldDecision, type Tier2SignificanceThreshold, type TierMultipliers, } from './config.js';
+export { computeConfigDiff, eventsFilePath as signalIngestionEventsFilePath, loadSignalIngestionConfigWithGovernance, writeSignalIngestionConfigChangedEvent, type LoadConfigWithGovernanceOptions, type LoadConfigWithGovernanceResult, type SignalIngestionConfigChange, type SignalIngestionConfigChangedEvent, type SignalIngestionConfigDiff, type WriteConfigChangeEventOpts, } from './governance-events.js';
+export { clusterSignals, clusterSignalsWithResidency, computeClusterId, cosineSimilarity, type ClusterSignalsOptions, type ClusterSignalsWithResidencyOptions, type ClusteredSignalInput, type ClusteringAlgorithmUsed, type ClusteringResult, type ClusteringResultWithResidency, type DemandCluster, } from './clustering.js';
+export { clusterRequiresSegregation, composePostures, groupCostByRegion, makeStoredSignalRecord, partitionSignalsByRegion, readSignalRecordWithAudit, type CostAttributionRow, type CostByRegionBreakdown, type CrossRegionReadAuditEntry, type PostureRegimeInput, type StoredSignalRecord, } from './residency.js';
+export { assessClusterSignificance, assessTier2Significance, checkSignalResidency, classifySaResonance, computeBaselineStat, computeZScore, DEFAULT_FLOODING_DETECTION_CONFIG, detectFlooding, filterSignalsByResidency, InMemoryQuarantineStore, isSignalQuarantined, SA_WEIGHT_MULTIPLIERS, unquarantineFlooded, type AssessClusterSignificanceOptions, type AssessClusterSignificanceResult, type BaselineStat, type DetectFloodingOptions, type FloodingDetectionResult, type FloodingDetectionStatus, type FloodingSourceFlag, type PerSourceBaseline, type QuarantineEntry, type QuarantineStore, type ResidencyRegimeDeclaration, type SaResonanceBucket, type SignalFloodingDetectedDecision, type SignalFloodingFalsePositiveDecision, type SignalLowSaForReviewDecision, type SignalOutOfScopeDecision, type SignalResidencyCheck, type SignificanceAssessedCluster, type Tier2SignificanceReasons, type Tier2SignificanceState, type UnquarantineFloodedOptions, } from './significance.js';
+export { aggregateD1FromClusters, composeD1Inputs, computeClusterD1, enrichDemandSignalFromClusters, type AggregatedD1Result, type ClusterD1Score, type ClusterMatcher, type ComposeD1InputsArgs, type ComposedD1Result, type ComputeClusterD1Options, type EnrichDemandSignalArgs, type EnrichDemandSignalResult, } from './d1.js';
+import { SignalSourceRegistry } from './registry.js';
+/**
+ * Construct the default signal-source registry with the RFC-0030 OQ-13.1
+ * v0.3 v1 adapter set (env-var-based only):
+ *  - `signal-source-support-ticket` (Zendesk PAT via `SIGNAL_ZENDESK_PAT`)
+ *  - `signal-source-community-thread` (Discord / Slack bot token via
+ *    `SIGNAL_COMMUNITY_BOT_TOKEN` / custom)
+ *  - `signal-source-in-app-feedback` (API key via `SIGNAL_IN_APP_FEEDBACK_API_KEY`)
+ *  - `signal-source-manual` (no auth)
+ *
+ * OAuth-required adapters (full Salesforce / HubSpot / OAuth-scoped Zendesk)
+ * are NOT included; they defer to the future credential-management RFC and
+ * would be REFUSED at registration by the `requiresOAuth = true` gate.
+ *
+ * The default constructions DO NOT enable env-var probing (`probeEnvVar:
+ * false`) so the in-memory test pattern continues to work. Production
+ * deployments should pass `probeEnvVar: true` explicitly per adapter.
+ */
+export declare function createDefaultSignalSourceRegistry(): SignalSourceRegistry;
+//# sourceMappingURL=index.d.ts.map

package/dist/signal-ingestion/index.js

@@ -0,0 +1,53 @@
+export { AdapterCredentialInvalid, AdapterCredentialNotConfigured, AdapterCredentialRejected, AdapterRequiresCredentialMgmtRfc, ManualSignalIncomplete, ManualSignalRateLimitExceeded, SignalSourceUnavailable, UnknownSignalSource, } from './errors.js';
+export { SignalSourceRegistry, fetchSignalsFromAvailableAdapters, getSignalSourceAdapter, } from './registry.js';
+export { SupportTicketSignalSourceAdapter, DEFAULT_SUPPORT_TICKET_ENV_VAR, } from './adapters/support-ticket.js';
+export { CommunityThreadSignalSourceAdapter, DEFAULT_COMMUNITY_THREAD_ENV_VAR, } from './adapters/community-thread.js';
+export { InAppFeedbackSignalSourceAdapter, DEFAULT_IN_APP_FEEDBACK_ENV_VAR, } from './adapters/in-app-feedback.js';
+export { ManualSignalSourceAdapter, DEFAULT_MANUAL_DAILY_CAP_PER_OPERATOR, utcDateKey, } from './adapters/manual.js';
+// RFC-0030 OQ-13.4 v0.3 — manual-share quality metric
+export { computeManualShareMetric, defaultIsManualSignal, DEFAULT_MANUAL_SHARE_MIN_POPULATION, DEFAULT_MANUAL_SHARE_WARNING_THRESHOLD, DEFAULT_MANUAL_SHARE_WINDOW_DAYS, } from './manual-share-metric.js';
+// RFC-0030 Phase 2 — classification
+export { classifySignals, computeRecencyDecay, computeSignalWeight, resolveCustomerTier, resolveIcpResonance, tokenize, } from './classifier.js';
+export { loadSignalIngestionConfig, loadSignalIngestionConfigWithDeprecations, DEFAULT_SIGNAL_INGESTION_CONFIG, DEFAULT_SIGNAL_INGESTION_CONFIG_PATH, SignalIngestionConfigError, } from './config.js';
+// RFC-0030 §11 / AISDLC-348 Phase 6 — governance event logging
+export { computeConfigDiff, eventsFilePath as signalIngestionEventsFilePath, loadSignalIngestionConfigWithGovernance, writeSignalIngestionConfigChangedEvent, } from './governance-events.js';
+// RFC-0030 Phase 3 — clustering
+export { clusterSignals, clusterSignalsWithResidency, computeClusterId, cosineSimilarity, } from './clustering.js';
+// RFC-0030 OQ-13.3 re-walkthrough — per-stage residency enforcement +
+// multi-posture composition (AISDLC-432).
+export { clusterRequiresSegregation, composePostures, groupCostByRegion, makeStoredSignalRecord, partitionSignalsByRegion, readSignalRecordWithAudit, } from './residency.js';
+// RFC-0030 Phase 4 — significance threshold + SA resonance filter + flooding + residency
+export { assessClusterSignificance, assessTier2Significance, checkSignalResidency, classifySaResonance, computeBaselineStat, computeZScore, DEFAULT_FLOODING_DETECTION_CONFIG, detectFlooding, filterSignalsByResidency, InMemoryQuarantineStore, isSignalQuarantined, SA_WEIGHT_MULTIPLIERS, unquarantineFlooded, } from './significance.js';
+// RFC-0030 Phase 5 — D1 formula reformulation + RFC-0008 PPA integration
+export { aggregateD1FromClusters, composeD1Inputs, computeClusterD1, enrichDemandSignalFromClusters, } from './d1.js';
+import { CommunityThreadSignalSourceAdapter } from './adapters/community-thread.js';
+import { InAppFeedbackSignalSourceAdapter } from './adapters/in-app-feedback.js';
+import { ManualSignalSourceAdapter } from './adapters/manual.js';
+import { SupportTicketSignalSourceAdapter } from './adapters/support-ticket.js';
+import { SignalSourceRegistry } from './registry.js';
+/**
+ * Construct the default signal-source registry with the RFC-0030 OQ-13.1
+ * v0.3 v1 adapter set (env-var-based only):
+ *  - `signal-source-support-ticket` (Zendesk PAT via `SIGNAL_ZENDESK_PAT`)
+ *  - `signal-source-community-thread` (Discord / Slack bot token via
+ *    `SIGNAL_COMMUNITY_BOT_TOKEN` / custom)
+ *  - `signal-source-in-app-feedback` (API key via `SIGNAL_IN_APP_FEEDBACK_API_KEY`)
+ *  - `signal-source-manual` (no auth)
+ *
+ * OAuth-required adapters (full Salesforce / HubSpot / OAuth-scoped Zendesk)
+ * are NOT included; they defer to the future credential-management RFC and
+ * would be REFUSED at registration by the `requiresOAuth = true` gate.
+ *
+ * The default constructions DO NOT enable env-var probing (`probeEnvVar:
+ * false`) so the in-memory test pattern continues to work. Production
+ * deployments should pass `probeEnvVar: true` explicitly per adapter.
+ */
+export function createDefaultSignalSourceRegistry() {
+    const registry = new SignalSourceRegistry();
+    registry.register(new SupportTicketSignalSourceAdapter());
+    registry.register(new CommunityThreadSignalSourceAdapter());
+    registry.register(new InAppFeedbackSignalSourceAdapter());
+    registry.register(new ManualSignalSourceAdapter());
+    return registry;
+}
+//# sourceMappingURL=index.js.map

package/dist/signal-ingestion/manual-share-metric.d.ts

@@ -0,0 +1,93 @@
+/**
+ * RFC-0030 OQ-13.4 v0.3 re-walkthrough — manual-share quality metric.
+ *
+ * Tracks the rolling `manualSignals / totalSignals` ratio over a configurable
+ * window (default 7d). When the share exceeds the configured threshold
+ * (default 0.30) on a population that's large enough to be meaningful, emit
+ * `Decision: manual-signal-share-elevated` — a WARNING (not a block) that
+ * the pipeline is acting as a data-entry tool rather than automated
+ * demand-detection (architectural anti-pattern).
+ *
+ * Design decisions:
+ *  - Window is computed against `asOf` (defaults to `new Date()`) so tests
+ *    can drive a deterministic clock.
+ *  - Signals are bucketed by `sourceTimestamp` (NOT receipt time); this
+ *    matches the spirit of the metric ("what fraction of recent SOURCE
+ *    activity was manual"). Operator-attested manual signals carry their
+ *    sourceTimestamp = observation time, so the bucketing is honest.
+ *  - When `totalSignals == 0` over the window, returns `manualShare: 0` and
+ *    `elevated: false` (no division-by-zero, no false alarms on empty windows).
+ *  - The metric does NOT mutate signals — it observes a population and
+ *    returns a verdict. Caller (typically the pipeline orchestrator step
+ *    that wires Phase 4 outputs) emits the Decision when `elevated` is true.
+ */
+import type { ManualSignalShareElevatedDecision, RawSignal } from './types.js';
+/** Default window (rolling) over which the manual-share ratio is computed. */
+export declare const DEFAULT_MANUAL_SHARE_WINDOW_DAYS = 7;
+/** Default warning threshold (manual / total) above which the Decision fires. */
+export declare const DEFAULT_MANUAL_SHARE_WARNING_THRESHOLD = 0.3;
+/**
+ * Minimum total-signals count before we'll fire the elevated Decision.
+ * Prevents thrashing on tiny populations (1 manual + 1 total = 100% share
+ * fires spuriously). Tunable per-deployment if the framework default doesn't
+ * fit.
+ */
+export declare const DEFAULT_MANUAL_SHARE_MIN_POPULATION = 5;
+/**
+ * Per-signal source classifier: returns `true` when the signal came from a
+ * manual-entry adapter. The check is name-based to keep the helper
+ * decoupled from the `ManualSignalSourceAdapter` class — sources are
+ * identified by their `SignalSourceName`, and `signal-source-manual` is the
+ * canonical name.
+ *
+ * Tests can pass a custom predicate via `ManualShareMetricOptions.isManual`
+ * when modelling derivative manual-entry adapters.
+ */
+export declare function defaultIsManualSignal(signal: RawSignal): boolean;
+/** Inputs for `computeManualShareMetric()`. */
+export interface ManualShareMetricOptions {
+    /** Rolling window in days. Defaults to `DEFAULT_MANUAL_SHARE_WINDOW_DAYS` (7). */
+    windowDays?: number;
+    /** Warning threshold. Defaults to `DEFAULT_MANUAL_SHARE_WARNING_THRESHOLD` (0.30). */
+    shareWarningThreshold?: number;
+    /** Reference time for the rolling window. Defaults to `new Date()`. */
+    asOf?: Date;
+    /**
+     * Minimum total-signal count required before the elevated Decision can
+     * fire. Defaults to `DEFAULT_MANUAL_SHARE_MIN_POPULATION` (5). Prevents
+     * spurious alarms on tiny populations.
+     */
+    minPopulation?: number;
+    /** Override the manual-signal classifier. Defaults to `defaultIsManualSignal`. */
+    isManual?: (signal: RawSignal) => boolean;
+}
+/** Result of `computeManualShareMetric()`. */
+export interface ManualShareMetricResult {
+    /** Rolling manual / total ratio over the window. `0` when totalSignals is 0. */
+    manualShare: number;
+    /** Number of manual signals in the window. */
+    manualSignals: number;
+    /** Total number of signals in the window. */
+    totalSignals: number;
+    /** The window the metric was computed over (in days). */
+    windowDays: number;
+    /** Whether the elevated Decision should fire. */
+    elevated: boolean;
+    /**
+     * The Decision record, populated IFF `elevated` is `true`. Caller can
+     * forward this directly into the catalog without re-constructing the
+     * envelope.
+     */
+    decision?: ManualSignalShareElevatedDecision;
+}
+/**
+ * Compute the rolling manual-share metric on the supplied signal population.
+ *
+ * Bucketing rule: a signal is in the window IFF
+ *   `signal.sourceTimestamp >= asOf - windowDays`.
+ *
+ * The result is suitable for streaming back to the operator as a quality
+ * signal AND for forwarding to the RFC-0035 catalog when `elevated` fires.
+ */
+export declare function computeManualShareMetric(signals: readonly RawSignal[], options?: ManualShareMetricOptions): ManualShareMetricResult;
+//# sourceMappingURL=manual-share-metric.d.ts.map

package/dist/signal-ingestion/manual-share-metric.js

@@ -0,0 +1,106 @@
+/**
+ * RFC-0030 OQ-13.4 v0.3 re-walkthrough — manual-share quality metric.
+ *
+ * Tracks the rolling `manualSignals / totalSignals` ratio over a configurable
+ * window (default 7d). When the share exceeds the configured threshold
+ * (default 0.30) on a population that's large enough to be meaningful, emit
+ * `Decision: manual-signal-share-elevated` — a WARNING (not a block) that
+ * the pipeline is acting as a data-entry tool rather than automated
+ * demand-detection (architectural anti-pattern).
+ *
+ * Design decisions:
+ *  - Window is computed against `asOf` (defaults to `new Date()`) so tests
+ *    can drive a deterministic clock.
+ *  - Signals are bucketed by `sourceTimestamp` (NOT receipt time); this
+ *    matches the spirit of the metric ("what fraction of recent SOURCE
+ *    activity was manual"). Operator-attested manual signals carry their
+ *    sourceTimestamp = observation time, so the bucketing is honest.
+ *  - When `totalSignals == 0` over the window, returns `manualShare: 0` and
+ *    `elevated: false` (no division-by-zero, no false alarms on empty windows).
+ *  - The metric does NOT mutate signals — it observes a population and
+ *    returns a verdict. Caller (typically the pipeline orchestrator step
+ *    that wires Phase 4 outputs) emits the Decision when `elevated` is true.
+ */
+/** Default window (rolling) over which the manual-share ratio is computed. */
+export const DEFAULT_MANUAL_SHARE_WINDOW_DAYS = 7;
+/** Default warning threshold (manual / total) above which the Decision fires. */
+export const DEFAULT_MANUAL_SHARE_WARNING_THRESHOLD = 0.3;
+/**
+ * Minimum total-signals count before we'll fire the elevated Decision.
+ * Prevents thrashing on tiny populations (1 manual + 1 total = 100% share
+ * fires spuriously). Tunable per-deployment if the framework default doesn't
+ * fit.
+ */
+export const DEFAULT_MANUAL_SHARE_MIN_POPULATION = 5;
+/**
+ * Per-signal source classifier: returns `true` when the signal came from a
+ * manual-entry adapter. The check is name-based to keep the helper
+ * decoupled from the `ManualSignalSourceAdapter` class — sources are
+ * identified by their `SignalSourceName`, and `signal-source-manual` is the
+ * canonical name.
+ *
+ * Tests can pass a custom predicate via `ManualShareMetricOptions.isManual`
+ * when modelling derivative manual-entry adapters.
+ */
+export function defaultIsManualSignal(signal) {
+    const adapterName = signal.metadata?.['adapterName'];
+    if (adapterName === 'signal-source-manual')
+        return true;
+    // Heuristic fallback: presence of `attestedBy` is the structural signature
+    // of a manual-entered signal even when metadata is missing the adapterName.
+    return typeof signal.attestedBy === 'string' && signal.attestedBy.trim().length > 0;
+}
+/**
+ * Compute the rolling manual-share metric on the supplied signal population.
+ *
+ * Bucketing rule: a signal is in the window IFF
+ *   `signal.sourceTimestamp >= asOf - windowDays`.
+ *
+ * The result is suitable for streaming back to the operator as a quality
+ * signal AND for forwarding to the RFC-0035 catalog when `elevated` fires.
+ */
+export function computeManualShareMetric(signals, options = {}) {
+    const windowDays = options.windowDays ?? DEFAULT_MANUAL_SHARE_WINDOW_DAYS;
+    const threshold = options.shareWarningThreshold ?? DEFAULT_MANUAL_SHARE_WARNING_THRESHOLD;
+    const asOf = options.asOf ?? new Date();
+    const minPopulation = options.minPopulation ?? DEFAULT_MANUAL_SHARE_MIN_POPULATION;
+    const isManual = options.isManual ?? defaultIsManualSignal;
+    const windowStart = new Date(asOf.getTime() - windowDays * 24 * 60 * 60 * 1000);
+    let manualCount = 0;
+    let totalCount = 0;
+    for (const s of signals) {
+        if (s.sourceTimestamp < windowStart)
+            continue;
+        if (s.sourceTimestamp > asOf)
+            continue;
+        totalCount += 1;
+        if (isManual(s))
+            manualCount += 1;
+    }
+    const manualShare = totalCount === 0 ? 0 : manualCount / totalCount;
+    const elevated = totalCount >= minPopulation && manualShare > threshold;
+    const result = {
+        manualShare,
+        manualSignals: manualCount,
+        totalSignals: totalCount,
+        windowDays,
+        elevated,
+    };
+    if (elevated) {
+        result.decision = {
+            type: 'Decision',
+            decision: 'manual-signal-share-elevated',
+            manualShare,
+            threshold,
+            windowDays,
+            manualSignals: manualCount,
+            totalSignals: totalCount,
+            message: `Manual signal share elevated: ${(manualShare * 100).toFixed(1)}% over ` +
+                `last ${windowDays}d (${manualCount}/${totalCount}); threshold is ${(threshold * 100).toFixed(0)}%. ` +
+                `This may indicate the pipeline is being used as a data-entry tool rather than automated ` +
+                `demand-detection. Review adapter coverage + automation gaps.`,
+        };
+    }
+    return result;
+}
+//# sourceMappingURL=manual-share-metric.js.map