@lmzhen/dsh-evolution-skill-discovery 0.0.0-stage → 0.30.40

package/lib/types/adapter.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { CatalogEntry, ProjectionResult } from './projection.ts';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'skill-catalog': {
+            readonly kind: 'skill-catalog';
+            readonly form: 'catalog';
+            readonly entries: readonly CatalogEntry[];
+        } & ContextFormed;
+        'evolution-skill-projection': {
+            readonly kind: 'evolution-skill-projection';
+            readonly entries: readonly CatalogEntry[];
+            readonly hiddenNames: readonly string[];
+            readonly digest: string;
+        } & ContextFormed;
+    }
+}
+/** Provider the plugin supplies from SkillIndex + DomainMap + policy. */
+export interface ProjectionDigestStore {
+    get(agentKey: string): Promise<string | undefined>;
+    set(agentKey: string, digest: string): Promise<void>;
+}
+export interface CatalogProjectionProvider {
+    /** Optional persisted-session gate; false keeps the full catalog. */
+    shouldProject?(agent: Agent): boolean | Promise<boolean>;
+    project(input: {
+        readonly agent: Agent;
+        readonly catalogEntries: readonly CatalogEntry[];
+    }): ProjectionResult | Promise<ProjectionResult>;
+}
+/**
+ * Atomically replace one platform catalog message with the plugin projection.
+ * @param decision - the waterfall decision; only enter decisions are changed.
+ * @param result - a complete projection; incomplete results are ignored.
+ * @returns a new decision, or the original when no safe replacement exists.
+ */
+export declare function applyCatalogProjection(decision: PreStepDecision, result: ProjectionResult): PreStepDecision;
+/**
+ * Install the thin pre-step adapter. The listener is outer; it always calls
+ * next, only touches the platform catalog message, and fails open.
+ * @param ctx - plugin context.
+ * @param provider - projection provider backed by SkillIndex/DomainMap.
+ * @returns disposer from ctx.on.
+ */
+export declare function installCatalogProjection(ctx: Context, provider: CatalogProjectionProvider, digestStore?: ProjectionDigestStore): () => void;
+//# sourceMappingURL=adapter.d.ts.map

package/lib/types/assignment-queue.d.ts

@@ -0,0 +1,24 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { AssignmentQueue, AssignmentQueueEntry, AssignmentSubmission } from './assignment.ts';
+/** Durable assignment queue; process-local cache over one JSON file. */
+export declare class JsonAssignmentQueue implements AssignmentQueue {
+    private readonly entries;
+    private loaded;
+    private readonly io;
+    private readonly path;
+    constructor(io: EvolutionIoLike, path: string);
+    load(): Promise<void>;
+    private persist;
+    enqueue(input: {
+        key: string;
+        submission: AssignmentSubmission;
+        proposalDigest: string;
+        createdAt: number;
+    }): Promise<{
+        entry: AssignmentQueueEntry;
+        duplicate: boolean;
+    }>;
+    update(key: string, status: AssignmentQueueEntry['status'], pendingReason?: AssignmentQueueEntry['pendingReason']): Promise<void>;
+    list(): readonly AssignmentQueueEntry[];
+}
+//# sourceMappingURL=assignment-queue.d.ts.map

package/lib/types/assignment-sidecar.d.ts

@@ -0,0 +1,30 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { DomainAssignmentService } from './assignment.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'evolution/approval-decided'(payload: {
+            readonly record: {
+                readonly kind: string;
+                readonly args: unknown;
+            };
+            readonly action: 'approve' | 'reject';
+            readonly ok: boolean;
+        }): void;
+    }
+}
+/** Options for the create sidecar; it never writes skill content. */
+export interface AssignmentSidecarOptions {
+    readonly provider?: string | undefined;
+    readonly source?: string | undefined;
+    readonly onSubmitted?: (() => void) | undefined;
+}
+/**
+ * Observe successful create calls and submit their optional domain proposal.
+ * Direct creates submit immediately; staged creates submit only after approval.
+ * @param ctx - plugin context with tools and approval events.
+ * @param service - the one assignment service.
+ * @param options - provider/source identity for skillKey.
+ * @returns disposer for both listeners.
+ */
+export declare function installAssignmentSidecar(ctx: Context, service: DomainAssignmentService, options?: AssignmentSidecarOptions): () => void;
+//# sourceMappingURL=assignment-sidecar.d.ts.map

package/lib/types/assignment.d.ts

@@ -0,0 +1,131 @@
+import type { DomainMapStore, DomainNode } from './domain-map.ts';
+import type { SkillKey } from './identity.ts';
+/** Closed technical pending set; semantic uncertainty is not pending. */
+export type AssignmentPendingReason = 'invalid-id' | 'unknown-domain' | 'map-version-stale' | 'new-domain-conflict' | 'schema-invalid' | 'queue-unavailable';
+/** LLM proposal accepted by skill_manage create; code validates/mints. */
+export interface AssignmentProposal {
+    readonly mode: 'existing' | 'new';
+    readonly id?: string | undefined;
+    readonly proposed?: {
+        readonly title: string;
+        readonly purpose: string;
+        readonly inScope: readonly string[];
+        readonly outOfScope: readonly string[];
+        readonly triggers: readonly string[];
+        readonly evidenceSkillKeys: readonly string[];
+    } | undefined;
+    readonly secondaryDomainIds?: readonly string[] | undefined;
+    readonly confidence: number;
+    readonly reason: string;
+    readonly needsReview?: boolean | undefined;
+    readonly mapVersion: string;
+}
+/** One create-side queue submission. */
+export interface AssignmentSubmission {
+    readonly skillKey: SkillKey;
+    readonly threeFieldHash: string;
+    readonly modelInvocable: boolean;
+    readonly whenToUse?: string | undefined;
+    readonly proposal?: AssignmentProposal | undefined;
+    readonly now?: number | undefined;
+}
+/** Queue entry; key is the idempotency key. */
+export interface AssignmentQueueEntry {
+    readonly key: string;
+    readonly submission: AssignmentSubmission;
+    readonly proposalDigest: string;
+    readonly createdAt: number;
+    status: 'queued' | 'pending' | 'applied' | 'provisional';
+    pendingReason?: AssignmentPendingReason | undefined;
+}
+/** Queue abstraction used by the one assignment service. */
+export interface AssignmentQueue {
+    enqueue(entry: {
+        readonly key: string;
+        readonly submission: AssignmentSubmission;
+        readonly proposalDigest: string;
+        readonly createdAt: number;
+    }): Promise<{
+        entry: AssignmentQueueEntry;
+        duplicate: boolean;
+    }>;
+    update(key: string, status: AssignmentQueueEntry['status'], pendingReason?: AssignmentPendingReason): Promise<void>;
+}
+/** In-memory idempotent queue; production adapter can persist by key. */
+export declare class MemoryAssignmentQueue implements AssignmentQueue {
+    private readonly entries;
+    enqueue(input: {
+        key: string;
+        submission: AssignmentSubmission;
+        proposalDigest: string;
+        createdAt: number;
+    }): Promise<{
+        entry: AssignmentQueueEntry;
+        duplicate: boolean;
+    }>;
+    update(key: string, status: AssignmentQueueEntry['status'], pendingReason?: AssignmentPendingReason): Promise<void>;
+    list(): readonly AssignmentQueueEntry[];
+}
+/** Staged create: no queue entry until approval. */
+export interface StagedAssignment {
+    readonly id: string;
+    readonly submission: AssignmentSubmission;
+}
+/** Result of submit/process; create failure never appears here. */
+export type AssignmentResult = {
+    readonly kind: 'unclassified';
+    readonly reason: 'feature-off' | 'no-proposal' | 'not-model-invocable';
+} | {
+    readonly kind: 'queued';
+    readonly entry: AssignmentQueueEntry;
+    readonly duplicate: boolean;
+} | {
+    readonly kind: 'applied' | 'provisional';
+    readonly entry: AssignmentQueueEntry;
+    readonly mapVersion: string;
+} | {
+    readonly kind: 'pending';
+    readonly entry: AssignmentQueueEntry;
+    readonly reason: AssignmentPendingReason;
+};
+/** @returns idempotency key for one proposal observation. */
+export declare function assignmentKey(input: {
+    skillKey: SkillKey;
+    threeFieldHash: string;
+    proposalDigest: string;
+    mapVersion: string;
+}): string;
+/** @returns stable proposal digest; undefined proposal is digest of null. */
+export declare function proposalDigest(proposal: AssignmentProposal | undefined): string;
+/** @returns a closed-set pending reason or undefined when the proposal can enqueue. */
+export declare function validateProposal(proposal: AssignmentProposal): AssignmentPendingReason | undefined;
+/** @returns true only when whenToUse is covered by in/out/triggers; names alone do not count. */
+export declare function coveredByDomain(whenToUse: string, domain: Pick<DomainNode, 'inScope' | 'outOfScope' | 'triggers'>): boolean;
+/** One assignment sidecar service; the only map write path for create. */
+export declare class DomainAssignmentService {
+    private readonly queue;
+    private readonly store;
+    private readonly options;
+    constructor(queue: AssignmentQueue, store: DomainMapStore, options: {
+        readonly createClassificationEnabled: boolean;
+        readonly createCardsAvailable?: boolean;
+        readonly provisionalThreshold?: number;
+        readonly now?: () => number;
+    });
+    /** Stage a create proposal without queueing it. */
+    stage(submission: AssignmentSubmission): StagedAssignment;
+    /** Approve a staged create; only this call enqueues. */
+    approve(staged: StagedAssignment): Promise<AssignmentResult>;
+    /**
+     * Submit a create proposal after SkillLibrary.create succeeded.
+     * @param submission - skill identity, three-field hash, permission, proposal.
+     * @returns queue/pending/unclassified; never rolls back create.
+     */
+    submit(submission: AssignmentSubmission): Promise<AssignmentResult>;
+    /** Process one queued entry with the current map; CAS failure becomes pending. */
+    process(entry: AssignmentQueueEntry): Promise<AssignmentResult>;
+    /** Manually confirm one provisional domain; no semantic reclassification. */
+    confirm(domainId: string): Promise<boolean>;
+    private now;
+}
+//# sourceMappingURL=assignment.d.ts.map

package/lib/types/awareness.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Static 1–2 sentence awareness; no domain list/tree. */
+export declare const DISCOVERY_AWARENESS = "When skill coverage for a task is uncertain, the domain cards and skill_search can reduce it; search is optional, not a required step.";
+/** Register the static awareness section; absent systemPrompt is a no-op. */
+export declare function installDiscoveryAwareness(ctx: Context): () => void;
+//# sourceMappingURL=awareness.d.ts.map

package/lib/types/domain-bootstrap.d.ts

@@ -0,0 +1,14 @@
+import type { DomainMapSnapshot, DomainMapStore } from './domain-map.ts';
+import { type DomainGenerationProposal } from './domain-generation.ts';
+import type { SkillKey } from './identity.ts';
+/**
+ * Write an initial LLM domain proposal into the map. Code owns IDs and
+ * validation; no embedding taxonomy and no skill body is read.
+ * @param store - domain map owner.
+ * @param proposal - validated 8–12 domain proposal.
+ * @param skillKeys - evidence skill name -> stable skillKey.
+ * @param expectedMapVersion - CAS precondition.
+ * @returns committed snapshot.
+ */
+export declare function bootstrapDomainMap(store: DomainMapStore, proposal: DomainGenerationProposal, skillKeys: Readonly<Record<string, SkillKey>>, expectedMapVersion: string): Promise<DomainMapSnapshot>;
+//# sourceMappingURL=domain-bootstrap.d.ts.map

package/lib/types/domain-description.d.ts

@@ -0,0 +1,19 @@
+import type { DomainNode } from './domain-map.ts';
+/** Description lifecycle; stale is still servable, failed is not a new description. */
+export type DescriptionStatus = 'fresh' | 'stale' | 'failed';
+/** Events allowed to regenerate a domain description. */
+export type DescriptionRegenerationEvent = 'new' | 'split' | 'merge' | 'definition' | 'children' | 'skill-add';
+/** @returns true only for structural/definition events; normal skill add does not rewrite. */
+export declare function shouldRegenerateDescription(event: DescriptionRegenerationEvent): boolean;
+/** @returns true when the existing description may still serve. */
+export declare function descriptionIsServable(status: DescriptionStatus): boolean;
+/** @returns hash of child ids/description versions, never member skill names. */
+export declare function descriptionHashOf(domain: Pick<DomainNode, 'id' | 'descriptionVersion'>, children: readonly Pick<DomainNode, 'id' | 'descriptionVersion'>[]): string;
+/**
+ * Render a domain description from definition fields only. It never appends
+ * evidence/member skill names and is capped to 600 characters.
+ * @param domain - domain definition.
+ * @returns description text.
+ */
+export declare function renderDomainDescription(domain: Pick<DomainNode, 'name' | 'purpose' | 'inScope' | 'outOfScope' | 'triggers'>): string;
+//# sourceMappingURL=domain-description.d.ts.map

package/lib/types/domain-generation-prompt.d.ts

@@ -0,0 +1,14 @@
+/** Frozen initial domain-generation prompt; caller owns schema/IDs. */
+export declare const DOMAIN_GENERATION_PROMPT_VERSION = "v2";
+export declare const DOMAIN_GENERATION_PROMPT_V1 = "Group the provided skills into first-level domains.\nUse only name, description, and whenToUse; do not infer from skill bodies.\nProduce 8\u201312 domains that are coherent, distinct, task-recognizable, and useful as an awareness layer. A single skill is not a domain. Each domain has a name, one-sentence purpose, in-scope, out-of-scope, triggers, and evidence skill names that actually support it.\nPrefer clear boundaries over exhaustive coverage. If the evidence is weak, leave the skill unassigned rather than forcing it into a domain. Together the domains should cover the library where evidence supports it. Domain IDs are assigned by the caller.\nReturn only the structured result.";
+export interface DomainGenerationPromptOptions {
+    readonly minDomains?: number;
+    readonly maxDomains?: number;
+}
+/** @returns a parameterized initial-domain prompt; default 8–12. */
+export declare function buildDomainGenerationPrompt(options?: DomainGenerationPromptOptions): string;
+export declare const DOMAIN_GENERATION_PROMPT_V2: string;
+export declare const DOMAIN_GENERATION_PROMPT_HASH: string;
+/** Active prompt; v1 remains frozen for traceability. */
+export declare const DOMAIN_GENERATION_PROMPT: string;
+//# sourceMappingURL=domain-generation-prompt.d.ts.map

package/lib/types/domain-generation-service.d.ts

@@ -0,0 +1,23 @@
+import type { DomainMapSnapshot, DomainMapStore } from './domain-map.ts';
+import type { DomainGenerationProposal } from './domain-generation.ts';
+import type { GenerationSkillFact } from './domain-generation.ts';
+import type { SkillKey } from './identity.ts';
+/** External LLM adapter port; discovery owns validation/persistence only. */
+export interface DomainGenerationPort {
+    generate(input: {
+        readonly skills: readonly GenerationSkillFact[];
+        readonly prompt: string;
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<DomainGenerationProposal>;
+}
+/**
+ * Generate and persist the initial map only when the map has no domains.
+ * @param store - map owner.
+ * @param port - external LLM adapter.
+ * @param skills - name/description/whenToUse facts.
+ * @param skillKeys - evidence name -> stable key.
+ * @param expectedMapVersion - CAS precondition.
+ * @returns committed snapshot, or existing snapshot when already bootstrapped.
+ */
+export declare function initialDomainMap(store: DomainMapStore, port: DomainGenerationPort, skills: readonly GenerationSkillFact[], skillKeys: Readonly<Record<string, SkillKey>>, expectedMapVersion: string, signal?: AbortSignal, prompt?: string): Promise<DomainMapSnapshot>;
+//# sourceMappingURL=domain-generation-service.d.ts.map

package/lib/types/domain-generation.d.ts

@@ -0,0 +1,48 @@
+/** One three-field fact supplied to the domain generator. */
+export interface GenerationSkillFact {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string | undefined;
+}
+/** Input of the initial LLM domain-generation step. */
+export interface DomainGenerationInput {
+    readonly skills: readonly GenerationSkillFact[];
+}
+/** One LLM-proposed domain; no id, no parent pointer. */
+export interface GeneratedDomain {
+    readonly title: string;
+    readonly purpose: string;
+    readonly inScope: readonly string[];
+    readonly outOfScope: readonly string[];
+    readonly triggers: readonly string[];
+    readonly evidenceSkillKeys: readonly string[];
+}
+/** Raw LLM proposal. */
+export interface DomainGenerationProposal {
+    readonly domains: readonly GeneratedDomain[];
+}
+/** Normalized domain after code mints stable IDs. */
+export interface MintedDomain extends GeneratedDomain {
+    readonly id: string;
+}
+/** Validation result; errors are stable strings for retry/observability. */
+export type DomainGenerationValidation = {
+    readonly ok: true;
+    readonly domains: readonly MintedDomain[];
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/** @returns stable id derived from title, not the title itself. */
+export declare function mintDomainId(title: string): string;
+/** @returns direct for <=100 skills; prechunk-eligible above 100. */
+export declare function domainGenerationMode(skillCount: number): 'direct' | 'prechunk-eligible';
+/**
+ * Validate an initial generation proposal and mint ids. Does not call an LLM
+ * and does not read skill bodies; embedding taxonomy is rejected.
+ * @param input - skills the proposal was generated from.
+ * @param proposal - LLM output.
+ * @returns normalized domains or stable errors.
+ */
+export declare function validateDomainGeneration(input: DomainGenerationInput, proposal: DomainGenerationProposal): DomainGenerationValidation;
+//# sourceMappingURL=domain-generation.d.ts.map

package/lib/types/domain-map-store.d.ts

@@ -0,0 +1,39 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import type { DomainMapSnapshot, DomainMapStore, DomainMapWrite } from './domain-map.ts';
+/** File schema version supported by this store. */
+export declare const DOMAIN_MAP_SCHEMA_VERSION = 1;
+/** Typed failure for an invalid persisted file. */
+export declare class DomainMapCorruptError extends Error {
+    readonly code = "domain-map-corrupt";
+    constructor(message: string);
+}
+/** Typed failure for a CAS mismatch. */
+export declare class DomainMapVersionConflict extends Error {
+    readonly code = "domain-map-version-conflict";
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string);
+}
+/** Typed failure for an invalid write. */
+export declare class DomainMapValidationError extends Error {
+    readonly code = "domain-map-invalid";
+    constructor(message: string);
+}
+/**
+ * JSON-backed DomainMap owner. One file, schemaVersion, CAS mapVersion, and a
+ * best-effort .bak for rollback; no evolution-state tables or graph DB.
+ */
+export declare class DomainMapFileStore implements DomainMapStore {
+    private queue;
+    private readonly io;
+    private readonly path;
+    private readonly now;
+    constructor(io: EvolutionIoLike, path: string, now?: () => number);
+    private get backupPath();
+    private parse;
+    read(): Promise<DomainMapSnapshot>;
+    private commitNow;
+    commit(expectedMapVersion: string, next: DomainMapWrite): Promise<DomainMapSnapshot>;
+    rollback(): Promise<DomainMapSnapshot>;
+}
+//# sourceMappingURL=domain-map-store.d.ts.map

package/lib/types/domain-map.d.ts

@@ -0,0 +1,52 @@
+import type { SkillKey } from './identity.ts';
+/** One domain fact node; id is stable and never renamed by policy. */
+export interface DomainNode {
+    readonly id: string;
+    readonly name: string;
+    readonly purpose: string;
+    readonly description: string;
+    readonly inScope: readonly string[];
+    readonly outOfScope: readonly string[];
+    readonly triggers: readonly string[];
+    readonly parentIds: readonly string[];
+    readonly status: 'active' | 'provisional' | 'deprecated';
+    readonly version: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly descriptionHash: string;
+    readonly descriptionVersion: number;
+    readonly descriptionStatus: 'fresh' | 'stale' | 'failed';
+    readonly provenance: Readonly<Record<string, string>>;
+    readonly quality: Readonly<Record<string, number>>;
+}
+/** One skill-domain edge; skillKey is the global identity, not a display name. */
+export interface SkillDomainEdge {
+    readonly skillKey: SkillKey;
+    readonly domainId: string;
+    readonly role: 'primary' | 'secondary';
+    readonly confidence: number;
+    readonly source: 'create' | 'manual' | 'maintenance';
+    readonly skillHash: string;
+    readonly mapVersion: string;
+    readonly status: 'active' | 'stale' | 'pending';
+    readonly assignedAt: number;
+}
+/** Immutable view of the domain fact store. */
+export interface DomainMapSnapshot {
+    readonly mapVersion: string;
+    readonly domains: readonly DomainNode[];
+    readonly edges: readonly SkillDomainEdge[];
+}
+/** A committed domain-map write. */
+export interface DomainMapWrite {
+    readonly mapVersion: string;
+    readonly domains: readonly DomainNode[];
+    readonly edges: readonly SkillDomainEdge[];
+}
+/** Owner contract; G1 supplies the JSON-backed implementation. */
+export interface DomainMapStore {
+    read(): Promise<DomainMapSnapshot>;
+    commit(expectedMapVersion: string, next: DomainMapWrite): Promise<DomainMapSnapshot>;
+    rollback(): Promise<DomainMapSnapshot>;
+}
+//# sourceMappingURL=domain-map.d.ts.map

package/lib/types/domain-metrics.d.ts

@@ -0,0 +1,41 @@
+import type { DomainMapSnapshot } from './domain-map.ts';
+import type { SkillKey } from './identity.ts';
+/** Optional labels for assignment accuracy; absent means unmeasured. */
+export interface DomainMetricLabels {
+    readonly expectedBySkill: Readonly<Record<SkillKey, string>>;
+    readonly predictedBySkill: Readonly<Record<SkillKey, string>>;
+    readonly newDomainIds?: readonly string[] | undefined;
+    readonly predictedNewDomainIds?: readonly string[] | undefined;
+}
+/** Recomputable domain/assignment metrics; no sentence locking. */
+export interface DomainMetricCounters {
+    readonly descriptionRewritten?: number | undefined;
+    readonly descriptionEligible?: number | undefined;
+    readonly refusedAssignments?: number | undefined;
+    readonly assignmentAttempts?: number | undefined;
+    readonly maxDomainsPerSkill?: number | undefined;
+}
+/** Recomputable domain/assignment metrics; no sentence locking. */
+export interface DomainMetrics {
+    readonly measured: boolean;
+    readonly visibleSkills: number;
+    readonly coverage: number | null;
+    readonly unclassifiedRatio: number | null;
+    readonly emptyDomainCount: number;
+    readonly crossDomainRatio: number | null;
+    readonly pendingRate: number | null;
+    readonly assignmentAccuracy: number | null;
+    readonly newDomainPrecision: number | null;
+    readonly descriptionRewriteRate: number | null;
+    readonly staleDescriptionRatio: number | null;
+    readonly overAssignmentRate: number | null;
+    readonly refusalRate: number | null;
+}
+/**
+ * @param snapshot - domain facts.
+ * @param visibleSkillKeys - skills visible in this view.
+ * @param labels - optional assignment labels.
+ * @returns metrics; null means the denominator is zero/unmeasured.
+ */
+export declare function computeDomainMetrics(snapshot: DomainMapSnapshot, visibleSkillKeys: ReadonlySet<SkillKey>, labels?: DomainMetricLabels, counters?: DomainMetricCounters): DomainMetrics;
+//# sourceMappingURL=domain-metrics.d.ts.map

package/lib/types/domain-policy.d.ts

@@ -0,0 +1,34 @@
+/** One policy layer; only these fields are user-editable. */
+export type DomainPolicyMode = 'off' | 'auto' | 'on';
+export interface DomainPolicyLayer {
+    readonly mode?: DomainPolicyMode | undefined;
+    readonly pinDomains?: readonly string[] | undefined;
+    readonly disableDomains?: readonly string[] | undefined;
+    readonly revision?: string | undefined;
+}
+/** Effective policy consumed by projection; never written back to DomainMap. */
+export interface EffectiveDomainPolicy {
+    readonly mode: DomainPolicyMode;
+    readonly pinned: ReadonlySet<string>;
+    readonly disabled: ReadonlySet<string>;
+    readonly degraded: readonly string[];
+    readonly globalRevision?: string | undefined;
+    readonly workspaceRevision?: string | undefined;
+    readonly scopeRevision?: string | undefined;
+}
+/** Invalid policy layer (e.g. attempts to edit taxonomy). */
+export declare class DomainPolicyValidationError extends Error {
+    readonly code = "domain-policy-invalid";
+    constructor(message: string);
+}
+/**
+ * Merge global -> workspace -> scope policy. Disable wins over pin; unknown
+ * domains are ignored and reported as degraded.
+ * @param global - mandatory global layer.
+ * @param workspace - optional workspace overlay.
+ * @param scope - optional scope overlay.
+ * @param knownDomainIds - optional known ids for validation.
+ * @returns immutable effective policy.
+ */
+export declare function mergeDomainPolicy(global: DomainPolicyLayer, workspace?: DomainPolicyLayer, scope?: DomainPolicyLayer, knownDomainIds?: ReadonlySet<string>): EffectiveDomainPolicy;
+//# sourceMappingURL=domain-policy.d.ts.map

package/lib/types/domain-projection.d.ts

@@ -0,0 +1,43 @@
+import type { DomainMapSnapshot } from './domain-map.ts';
+import type { EffectiveDomainPolicy } from './domain-policy.ts';
+import type { SkillIndexRow } from './identity.ts';
+import { type CatalogEntry, type ProjectionResult } from './projection.ts';
+/** Input for one view's domain/catalog projection. */
+export interface DomainProjectionInput {
+    readonly entries: readonly CatalogEntry[];
+    readonly rows: readonly SkillIndexRow[];
+    readonly complete: boolean;
+    readonly mapStale?: boolean | undefined;
+    readonly searchAvailable?: boolean | undefined;
+    readonly mode?: 'off' | 'shadow' | 'on' | undefined;
+    readonly snapshot: DomainMapSnapshot;
+    readonly policy: EffectiveDomainPolicy;
+    readonly viewKey: string;
+    readonly scope: string;
+    readonly mapVersion: string;
+    readonly policyDigest: string;
+    readonly viewCatalogDigest: string;
+    readonly adapterVersion: string;
+    readonly projectionSchemaVersion: string;
+    readonly discoveryMode: string;
+    readonly maxCards?: number | undefined;
+    readonly tokenBudget?: number | undefined;
+    readonly now?: number | undefined;
+    readonly staleAfterHours?: number | undefined;
+    readonly maxVisibleDepth?: number | undefined;
+}
+/**
+ * Build L1 cards and the hidden set for one view, then delegate the pure
+ * catalog rewrite. Structural staleness fails open; description staleness does not.
+ * @param input - rows, domain facts, policy, and identity inputs.
+ * @returns projection result with cards and hidden names.
+ */
+export declare function hiddenRecoverable(hiddenNames: readonly string[], searchResultNames: ReadonlySet<string>): boolean;
+export declare function buildDomainProjection(input: DomainProjectionInput): ProjectionResult;
+/** @returns true when shadow evidence is sufficient to promote to on. */
+export declare function canPromoteShadow(input: {
+    readonly samples: number;
+    readonly hiddenRecoverableRate: number;
+    readonly silentMisses: number;
+}): boolean;
+//# sourceMappingURL=domain-projection.d.ts.map

package/lib/types/domain-quality.d.ts

@@ -0,0 +1,17 @@
+import type { DomainNode } from './domain-map.ts';
+/** Stable quality issue codes. */
+export type DomainQualityIssue = 'empty-purpose' | 'vague-purpose' | 'empty-in-scope' | 'empty-out-of-scope' | 'empty-triggers' | 'overlaps-peer' | 'indistinguishable';
+/** Quality result is evidence, not an automatic mutation. */
+export interface DomainQualityResult {
+    readonly passed: boolean;
+    readonly issues: readonly DomainQualityIssue[];
+    readonly score: number;
+}
+/**
+ * Evaluate whether a domain definition is specific, triggered, and distinct.
+ * @param domain - candidate domain.
+ * @param peers - other visible domains.
+ * @returns auditable issues; does not mutate the candidate.
+ */
+export declare function evaluateDomainQuality(domain: Pick<DomainNode, 'name' | 'purpose' | 'inScope' | 'outOfScope' | 'triggers'>, peers: readonly Pick<DomainNode, 'name' | 'purpose' | 'inScope' | 'outOfScope' | 'triggers'>[]): DomainQualityResult;
+//# sourceMappingURL=domain-quality.d.ts.map

package/lib/types/domain-view.d.ts

@@ -0,0 +1,15 @@
+import type { DomainMapSnapshot } from './domain-map.ts';
+import type { SkillKey } from './identity.ts';
+/** Per-view membership counts; unclassified is virtual, never a domain id. */
+export interface DomainViewCounts {
+    readonly byDomain: ReadonlyMap<string, number>;
+    readonly unclassified: number;
+}
+/**
+ * Count visible skills by active domain membership.
+ * @param snapshot - global domain facts.
+ * @param visibleSkillKeys - skill keys visible in this view.
+ * @returns per-domain member counts plus the unclassified virtual count.
+ */
+export declare function domainViewCounts(snapshot: DomainMapSnapshot, visibleSkillKeys: ReadonlySet<SkillKey>): DomainViewCounts;
+//# sourceMappingURL=domain-view.d.ts.map

package/lib/types/features.d.ts

@@ -0,0 +1,11 @@
+/** Discovery feature gates; v0 defaults everything off. */
+export type DiscoveryMode = 'off' | 'shadow' | 'on';
+export interface DiscoveryFeatureConfig {
+    readonly projectionEnabled: boolean;
+    readonly searchEnabled: boolean;
+    readonly createClassificationEnabled: boolean;
+    readonly discoveryMode: DiscoveryMode;
+}
+export declare const V0_DISCOVERY_FEATURES: DiscoveryFeatureConfig;
+export declare function canClassifyAtCreate(config: DiscoveryFeatureConfig, hasCreateDomainCards: boolean): boolean;
+//# sourceMappingURL=features.d.ts.map