@extrovert.dev/sdk 0.1.0-pre.7 → 0.1.0-pre.9

package/dist/index.d.cts

@@ -6,7 +6,7 @@
  * on 429/5xx, honors `Retry-After`, and surfaces every failure as a typed {@link ApiError}.
  */
 /** The library version, surfaced in the User-Agent. Kept in sync with package.json by build. */
-declare const SDK_VERSION = "0.1.0-pre.7";
+declare const SDK_VERSION = "0.1.0-pre.9";
 interface RetryOptions {
     /** Max retry attempts for idempotent requests on 429/5xx/network errors. Default 2. */
     maxRetries: number;
@@ -781,6 +781,7 @@ interface ReviewTurn {
 }
 /** Filters for listing review requests (spec §5.2). */
 interface ListReviewsParams {
+    composer?: "me";
     state?: ReviewState | ReviewState[];
     category_id?: string;
     inbox?: string;
@@ -911,6 +912,7 @@ interface ReviewEventCursor {
 }
 /** Drain result for list/wait: un-acked events in FIFO seq order + cursors. */
 interface ReviewEventsResult {
+    pending_reviews?: number;
     events: ReviewEvent[];
     cursors?: ReviewEventCursor[];
 }
@@ -928,6 +930,12 @@ interface ListReviewEventsParams {
  * agent-attributed: the deliberate cross-agent-404 exception. Opaque ids only.
  */
 interface Category {
+    /** Logical accepted messages in this authorized project, counted by creation time. */
+    message_count_7d?: number;
+    message_count_30d?: number;
+    message_count_90d?: number;
+    last_used_at?: string;
+    pending_review_count?: number;
     id: string;
     name: string;
     description: string;
@@ -944,6 +952,9 @@ interface Category {
 }
 /** Browse filter for the category registry (spec §5.5). */
 interface ListCategoriesParams {
+    sort?: "popular" | "messages_7d" | "messages_90d" | "last_used" | "pending_reviews" | "name";
+    limit?: number;
+    page?: string;
     /** Pure lexical substring filter over name+description (every token must match; NO LLM). */
     match?: string;
 }
@@ -1207,6 +1218,8 @@ interface Rule {
     author_kind: "agent" | "human";
     created_at: IsoTimestamp;
     updated_at: IsoTimestamp;
+    source_review_id?: string;
+    source_turn_id?: string;
 }
 /** Filter for the ordered get_rules read (spec §5.4; §7). */
 interface GetRulesParams {
@@ -1228,8 +1241,8 @@ interface RuleSnapshot extends Page<Rule> {
  *
  * Layering (org/project): an agent-plane save is ALWAYS project-layer: the saved
  * rule's `rule_layer` is `project`, bound to the calling key's project. There is no
- * settable `rule_layer` here: an agent cannot create org-layer / house-style
- * (`rule_layer="org"`) rules in v1; authoring org rules is a console/admin action.
+ * settable `rule_layer` here: this method cannot create org-layer rules. Use learnFromReview for
+ * authenticated reviewer feedback, including organization house style.
  * (`scope: "general"` still means a house-style rule WITHIN the project layer :
  * `scope` is the category axis, `rule_layer` is the ownership axis.)
  */
@@ -1891,6 +1904,24 @@ interface WhoAmI {
     key_id: string;
     scopes: Scope[];
 }
+/** Learn writing guidance from an authenticated human turn on your review. */
+interface LearnReviewRuleRequest {
+    client_id: string;
+    source_turn_id: string;
+    rule_text: string;
+    target: "org_house" | "project_general" | "category";
+    category_id?: string;
+    kind?: "soft" | "hard";
+    supersedes_id?: string;
+}
+interface LearnedReviewRule {
+    rule: Rule;
+    source_review_id: string;
+    source_turn_id: string;
+    human_id: string;
+    audit_id: string;
+    propagation: "queued";
+}
 
 /**
  * The ONE list envelope + opaque-cursor iteration (redesign §5.2 / §6.2).
@@ -2067,6 +2098,7 @@ interface Transport {
     getScanBacklogStatus(categoryId: string, signal?: AbortSignal): Promise<ScanBacklogStatus>;
     getCategoryPacingState(categoryId: string, signal?: AbortSignal): Promise<CategoryPacingState>;
     getRules(params: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
+    learnReviewRule(reviewId: string, req: LearnReviewRuleRequest, signal?: AbortSignal): Promise<LearnedReviewRule>;
     saveRule(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
     promoteRule(ruleId: string, toScope: "general" | "category", signal?: AbortSignal): Promise<Rule>;
     retireRule(ruleId: string, signal?: AbortSignal): Promise<Rule>;
@@ -2239,6 +2271,7 @@ declare class MockBackend {
      * is a pure lexical filter (every token must appear in name+description) - NO LLM,
      * mirroring the server.
      */
+    private categoryUsage;
     listCategories(params?: ListCategoriesParams): Page<Category>;
     /** Get one category (mock), or undefined when not found. */
     getCategory(categoryId: string): Category | undefined;
@@ -2287,6 +2320,8 @@ declare class MockBackend {
     /** Get the ORDERED active rule set (mock) - §7 ladder + category-before-general. */
     getRules(params?: GetRulesParams): RuleSnapshot;
     /** Save / edit a rule (mock) - append-only by supersession (D11). */
+    private learnedRules;
+    learnReviewRule(reviewId: string, req: LearnReviewRuleRequest): LearnedReviewRule;
     saveRule(req: SaveRuleRequest): Rule;
     /** Promote a rule between layers (mock, via supersession), or undefined when unknown. */
     promoteRule(ruleId: string, toScope: "general" | "category"): Rule | undefined;
@@ -3253,14 +3288,16 @@ declare class Categories {
  */
 declare class Rules {
     private readonly ctx;
+    /** Learn category or organization house rules from verified human review feedback. */
+    learnFromReview(reviewId: string, req: LearnReviewRuleRequest, signal?: AbortSignal): Promise<LearnedReviewRule>;
     constructor(ctx: ResourceContext);
     /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
     get(params?: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
     /**
      * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
      * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
-     * key's project. Agents cannot author org-layer / house-style (`rule_layer:"org"`)
-     * rules in v1: that is a console/admin action.
+     * key's project. For all authenticated reviewer feedback use learnFromReview at the intended
+     * organization, project, or category scope. This method is project maintenance only.
      */
     save(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
     /** Promote a rule between the category and general/house-style layers. */
@@ -3963,7 +4000,7 @@ declare function signWebhook(secret: string, body: string, timestampSeconds: num
  *
  * ## Provisional, pre-1.0 (0.x)
  *
- * {@link CONTRACT_VERSION} is **`0.1.0-pre.7`** - a deliberately **provisional**, pre-1.0
+ * {@link CONTRACT_VERSION} is **`0.1.0-pre.9`** - a deliberately **provisional**, pre-1.0
  * contract. It is open and documented, but it MAY still evolve before 1.0: there
  * are no external users yet, and the **D20 shared-pool auto-send governor** is a
  * hard prerequisite before onboarding external users. Pin the version; expect
@@ -4020,12 +4057,12 @@ interface DiffJson {
 /**
  * The published version of the Extrovert Review-Loop open contract (D14).
  *
- * **`0.1.0-pre.7` - PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
+ * **`0.1.0-pre.9` - PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
  * `package.json` version) and aligned to the openapi `info.version`. Open and
  * documented, but MAY still evolve before 1.0 (no external users yet; the D20
  * shared-pool governor is required before external users). Pin it.
  */
-declare const CONTRACT_VERSION: "0.1.0-pre.7";
+declare const CONTRACT_VERSION: "0.1.0-pre.9";
 /** The stability posture of a published contract version. */
 type ContractStability = "provisional" | "stable";
 /**
@@ -4068,4 +4105,4 @@ interface ContractManifest {
  */
 declare const CONTRACT_MANIFEST: ContractManifest;
 
-export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, Commerce, type CommerceBlocker, type CommerceRequest, type CommerceRequestKind, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainQuote, type DomainReadiness, type DomainRecord, type DomainScope, type DomainStatusEvent, type DomainStatusEventPage, type DomainWaitResult, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type List, type ListCategoriesParams, type ListCommerceRequestsParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MailboxQuickstart, type MailboxQuickstartCall, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, type QuoteDomainRequest, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RequestDomainPurchaseRequest, type RequestPlanChangeRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, type RuleSnapshot, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };
+export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, Commerce, type CommerceBlocker, type CommerceRequest, type CommerceRequestKind, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainQuote, type DomainReadiness, type DomainRecord, type DomainScope, type DomainStatusEvent, type DomainStatusEventPage, type DomainWaitResult, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type LearnReviewRuleRequest, type LearnedReviewRule, type List, type ListCategoriesParams, type ListCommerceRequestsParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MailboxQuickstart, type MailboxQuickstartCall, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, type QuoteDomainRequest, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RequestDomainPurchaseRequest, type RequestPlanChangeRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, type RuleSnapshot, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * on 429/5xx, honors `Retry-After`, and surfaces every failure as a typed {@link ApiError}.
  */
 /** The library version, surfaced in the User-Agent. Kept in sync with package.json by build. */
-declare const SDK_VERSION = "0.1.0-pre.7";
+declare const SDK_VERSION = "0.1.0-pre.9";
 interface RetryOptions {
     /** Max retry attempts for idempotent requests on 429/5xx/network errors. Default 2. */
     maxRetries: number;
@@ -781,6 +781,7 @@ interface ReviewTurn {
 }
 /** Filters for listing review requests (spec §5.2). */
 interface ListReviewsParams {
+    composer?: "me";
     state?: ReviewState | ReviewState[];
     category_id?: string;
     inbox?: string;
@@ -911,6 +912,7 @@ interface ReviewEventCursor {
 }
 /** Drain result for list/wait: un-acked events in FIFO seq order + cursors. */
 interface ReviewEventsResult {
+    pending_reviews?: number;
     events: ReviewEvent[];
     cursors?: ReviewEventCursor[];
 }
@@ -928,6 +930,12 @@ interface ListReviewEventsParams {
  * agent-attributed: the deliberate cross-agent-404 exception. Opaque ids only.
  */
 interface Category {
+    /** Logical accepted messages in this authorized project, counted by creation time. */
+    message_count_7d?: number;
+    message_count_30d?: number;
+    message_count_90d?: number;
+    last_used_at?: string;
+    pending_review_count?: number;
     id: string;
     name: string;
     description: string;
@@ -944,6 +952,9 @@ interface Category {
 }
 /** Browse filter for the category registry (spec §5.5). */
 interface ListCategoriesParams {
+    sort?: "popular" | "messages_7d" | "messages_90d" | "last_used" | "pending_reviews" | "name";
+    limit?: number;
+    page?: string;
     /** Pure lexical substring filter over name+description (every token must match; NO LLM). */
     match?: string;
 }
@@ -1207,6 +1218,8 @@ interface Rule {
     author_kind: "agent" | "human";
     created_at: IsoTimestamp;
     updated_at: IsoTimestamp;
+    source_review_id?: string;
+    source_turn_id?: string;
 }
 /** Filter for the ordered get_rules read (spec §5.4; §7). */
 interface GetRulesParams {
@@ -1228,8 +1241,8 @@ interface RuleSnapshot extends Page<Rule> {
  *
  * Layering (org/project): an agent-plane save is ALWAYS project-layer: the saved
  * rule's `rule_layer` is `project`, bound to the calling key's project. There is no
- * settable `rule_layer` here: an agent cannot create org-layer / house-style
- * (`rule_layer="org"`) rules in v1; authoring org rules is a console/admin action.
+ * settable `rule_layer` here: this method cannot create org-layer rules. Use learnFromReview for
+ * authenticated reviewer feedback, including organization house style.
  * (`scope: "general"` still means a house-style rule WITHIN the project layer :
  * `scope` is the category axis, `rule_layer` is the ownership axis.)
  */
@@ -1891,6 +1904,24 @@ interface WhoAmI {
     key_id: string;
     scopes: Scope[];
 }
+/** Learn writing guidance from an authenticated human turn on your review. */
+interface LearnReviewRuleRequest {
+    client_id: string;
+    source_turn_id: string;
+    rule_text: string;
+    target: "org_house" | "project_general" | "category";
+    category_id?: string;
+    kind?: "soft" | "hard";
+    supersedes_id?: string;
+}
+interface LearnedReviewRule {
+    rule: Rule;
+    source_review_id: string;
+    source_turn_id: string;
+    human_id: string;
+    audit_id: string;
+    propagation: "queued";
+}
 
 /**
  * The ONE list envelope + opaque-cursor iteration (redesign §5.2 / §6.2).
@@ -2067,6 +2098,7 @@ interface Transport {
     getScanBacklogStatus(categoryId: string, signal?: AbortSignal): Promise<ScanBacklogStatus>;
     getCategoryPacingState(categoryId: string, signal?: AbortSignal): Promise<CategoryPacingState>;
     getRules(params: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
+    learnReviewRule(reviewId: string, req: LearnReviewRuleRequest, signal?: AbortSignal): Promise<LearnedReviewRule>;
     saveRule(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
     promoteRule(ruleId: string, toScope: "general" | "category", signal?: AbortSignal): Promise<Rule>;
     retireRule(ruleId: string, signal?: AbortSignal): Promise<Rule>;
@@ -2239,6 +2271,7 @@ declare class MockBackend {
      * is a pure lexical filter (every token must appear in name+description) - NO LLM,
      * mirroring the server.
      */
+    private categoryUsage;
     listCategories(params?: ListCategoriesParams): Page<Category>;
     /** Get one category (mock), or undefined when not found. */
     getCategory(categoryId: string): Category | undefined;
@@ -2287,6 +2320,8 @@ declare class MockBackend {
     /** Get the ORDERED active rule set (mock) - §7 ladder + category-before-general. */
     getRules(params?: GetRulesParams): RuleSnapshot;
     /** Save / edit a rule (mock) - append-only by supersession (D11). */
+    private learnedRules;
+    learnReviewRule(reviewId: string, req: LearnReviewRuleRequest): LearnedReviewRule;
     saveRule(req: SaveRuleRequest): Rule;
     /** Promote a rule between layers (mock, via supersession), or undefined when unknown. */
     promoteRule(ruleId: string, toScope: "general" | "category"): Rule | undefined;
@@ -3253,14 +3288,16 @@ declare class Categories {
  */
 declare class Rules {
     private readonly ctx;
+    /** Learn category or organization house rules from verified human review feedback. */
+    learnFromReview(reviewId: string, req: LearnReviewRuleRequest, signal?: AbortSignal): Promise<LearnedReviewRule>;
     constructor(ctx: ResourceContext);
     /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
     get(params?: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
     /**
      * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
      * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
-     * key's project. Agents cannot author org-layer / house-style (`rule_layer:"org"`)
-     * rules in v1: that is a console/admin action.
+     * key's project. For all authenticated reviewer feedback use learnFromReview at the intended
+     * organization, project, or category scope. This method is project maintenance only.
      */
     save(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
     /** Promote a rule between the category and general/house-style layers. */
@@ -3963,7 +4000,7 @@ declare function signWebhook(secret: string, body: string, timestampSeconds: num
  *
  * ## Provisional, pre-1.0 (0.x)
  *
- * {@link CONTRACT_VERSION} is **`0.1.0-pre.7`** - a deliberately **provisional**, pre-1.0
+ * {@link CONTRACT_VERSION} is **`0.1.0-pre.9`** - a deliberately **provisional**, pre-1.0
  * contract. It is open and documented, but it MAY still evolve before 1.0: there
  * are no external users yet, and the **D20 shared-pool auto-send governor** is a
  * hard prerequisite before onboarding external users. Pin the version; expect
@@ -4020,12 +4057,12 @@ interface DiffJson {
 /**
  * The published version of the Extrovert Review-Loop open contract (D14).
  *
- * **`0.1.0-pre.7` - PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
+ * **`0.1.0-pre.9` - PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
  * `package.json` version) and aligned to the openapi `info.version`. Open and
  * documented, but MAY still evolve before 1.0 (no external users yet; the D20
  * shared-pool governor is required before external users). Pin it.
  */
-declare const CONTRACT_VERSION: "0.1.0-pre.7";
+declare const CONTRACT_VERSION: "0.1.0-pre.9";
 /** The stability posture of a published contract version. */
 type ContractStability = "provisional" | "stable";
 /**
@@ -4068,4 +4105,4 @@ interface ContractManifest {
  */
 declare const CONTRACT_MANIFEST: ContractManifest;
 
-export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, Commerce, type CommerceBlocker, type CommerceRequest, type CommerceRequestKind, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainQuote, type DomainReadiness, type DomainRecord, type DomainScope, type DomainStatusEvent, type DomainStatusEventPage, type DomainWaitResult, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type List, type ListCategoriesParams, type ListCommerceRequestsParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MailboxQuickstart, type MailboxQuickstartCall, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, type QuoteDomainRequest, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RequestDomainPurchaseRequest, type RequestPlanChangeRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, type RuleSnapshot, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };
+export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, Commerce, type CommerceBlocker, type CommerceRequest, type CommerceRequestKind, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainQuote, type DomainReadiness, type DomainRecord, type DomainScope, type DomainStatusEvent, type DomainStatusEventPage, type DomainWaitResult, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type LearnReviewRuleRequest, type LearnedReviewRule, type List, type ListCategoriesParams, type ListCommerceRequestsParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MailboxQuickstart, type MailboxQuickstartCall, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, type QuoteDomainRequest, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RequestDomainPurchaseRequest, type RequestPlanChangeRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, type RuleSnapshot, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };

package/dist/index.js

@@ -266,7 +266,7 @@ var CURRENT_API_VERSION = "2026-06-23";
 var API_VERSION_HEADER = "Extrovert-Version";
 
 // src/http.ts
-var SDK_VERSION = "0.1.0-pre.7";
+var SDK_VERSION = "0.1.0-pre.9";
 function buildUrl(baseUrl, path, query) {
   const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
   const rel = path.startsWith("/") ? path : `/${path}`;
@@ -936,6 +936,8 @@ ${parent.text}`;
 var MockBackend = class {
   constructor() {
     this.state = freshState();
+    /** Save / edit a rule (mock) - append-only by supersession (D11). */
+    this.learnedRules = /* @__PURE__ */ new Map();
   }
   reset() {
     this.state = freshState();
@@ -1817,8 +1819,21 @@ var MockBackend = class {
    * is a pure lexical filter (every token must appear in name+description) - NO LLM,
    * mirroring the server.
    */
+  categoryUsage(category) {
+    const now2 = Date.now();
+    const rows = [...this.state.reviews.values()].filter((r) => r.category_id === category.id && Date.parse(r.created_at) <= now2);
+    const count = (days) => rows.filter((r) => Date.parse(r.created_at) >= now2 - days * 864e5).length;
+    return {
+      ...category,
+      message_count_7d: count(7),
+      message_count_30d: count(30),
+      message_count_90d: count(90),
+      last_used_at: rows.map((r) => r.created_at).sort().slice(-1)[0],
+      pending_review_count: rows.filter((r) => ["needs_review", "in_review", "chatting", "rejected", "stale", "approved"].includes(r.state)).length
+    };
+  }
   listCategories(params = {}) {
-    let items = [...this.state.categories.values()].filter((c) => !c.merged_into).sort((a, b) => b.created_at.localeCompare(a.created_at));
+    let items = [...this.state.categories.values()].filter((c) => !c.merged_into).map((c) => this.categoryUsage(c)).sort((a, b) => b.created_at.localeCompare(a.created_at));
     const tokens = (params.match ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
     if (tokens.length) {
       items = items.filter((c) => {
@@ -1826,15 +1841,22 @@ var MockBackend = class {
         return tokens.every((t) => hay.includes(t));
       });
     }
-    return { items, total: items.length };
+    const field = { messages_7d: "message_count_7d", messages_90d: "message_count_90d", pending_reviews: "pending_review_count" }[params.sort] ?? "message_count_30d";
+    items.sort((a, b) => (params.sort === "name" ? a.name.toLowerCase().localeCompare(b.name.toLowerCase()) : params.sort === "last_used" ? 0 : (b[field] ?? 0) - (a[field] ?? 0)) || (b.last_used_at ?? "").localeCompare(a.last_used_at ?? "") || a.id.localeCompare(b.id));
+    const offset = params.page ? JSON.parse(Buffer.from(params.page, "base64url").toString()).o : 0;
+    const total = items.length, limit = params.limit ?? 100;
+    const next = offset + limit < total ? Buffer.from(JSON.stringify({ o: offset + limit, v: 1 })).toString("base64url") : void 0;
+    return { items: items.slice(offset, offset + limit), total, next_cursor: next };
   }
   /** Get one category (mock), or undefined when not found. */
   getCategory(categoryId) {
-    return this.state.categories.get(categoryId);
+    const category = this.state.categories.get(categoryId);
+    return category ? this.categoryUsage(category) : void 0;
   }
   /** Propose a category (mock): stands immediately, author_kind=agent (D9). */
   proposeCategory(req) {
     const name = req.name.trim();
+    if ([...this.state.categories.values()].some((c) => !c.merged_into && c.name.toLowerCase() === name.toLowerCase())) throw new ConflictError({ status: 409, code: "conflict", message: "Category name already exists; browse and reuse it." });
     if (!name) {
       throw new ValidationError({ status: 400, code: "invalid", message: "name is required" });
     }
@@ -2040,7 +2062,27 @@ var MockBackend = class {
       composition_token_expires_at: params.scope ? void 0 : new Date(Date.now() + 6e5).toISOString()
     };
   }
-  /** Save / edit a rule (mock) - append-only by supersession (D11). */
+  learnReviewRule(reviewId, req) {
+    const fingerprint = JSON.stringify({ reviewId, req });
+    const prior = this.learnedRules.get(req.client_id);
+    if (prior) {
+      if (prior.fingerprint !== fingerprint) throw new ValidationError({ status: 409, code: "conflict", message: "learning retry identity changed" });
+      return structuredClone(prior.result);
+    }
+    const turn = (this.state.reviewTurns.get(reviewId) ?? []).find((t) => t.id === req.source_turn_id);
+    if (!turn || turn.actor_kind !== "human" || !turn.actor_id) throw new ValidationError({ status: 403, code: "forbidden_scope", message: "learning requires authenticated human feedback" });
+    const rule = this.saveRule({ ...req, scope: req.target === "category" ? "category" : "general", source_review_id: reviewId, source_turn_id: turn.id });
+    rule.source_turn_id = turn.id;
+    rule.rule_layer = req.target === "org_house" ? "org" : "project";
+    if (req.target === "org_house") delete rule.project_id;
+    rule.source_review_id = reviewId;
+    rule.source_turn_id = turn.id;
+    const audit = [...this.state.ruleAudit.values()].find((entry) => entry.entity_id === rule.id);
+    audit.after_json = ruleSnapshotJSON(rule);
+    const result = { rule, source_review_id: reviewId, source_turn_id: turn.id, human_id: turn.actor_id, audit_id: audit.id, propagation: "queued" };
+    this.learnedRules.set(req.client_id, { fingerprint, result: structuredClone(result) });
+    return result;
+  }
   saveRule(req) {
     const text = req.rule_text.trim();
     if (!text) {
@@ -3681,6 +3723,7 @@ var HttpTransport = class {
       state: Array.isArray(params.state) ? params.state.join(",") : params.state,
       category_id: params.category_id,
       inbox: params.inbox,
+      composer: params.composer,
       limit: params.limit,
       page: params.page
     };
@@ -3763,10 +3806,12 @@ var HttpTransport = class {
     });
   }
   waitForReviewEvent(params, signal) {
+    const waitSeconds = Math.min(55, Math.max(1, params.wait_seconds ?? 55));
     return this.call({
       method: "GET",
       path: "/v1/reviews/events/wait",
-      query: { review_id: params.review_id, limit: params.limit, wait_seconds: params.wait_seconds },
+      query: { review_id: params.review_id, limit: params.limit, wait_seconds: waitSeconds },
+      timeoutMs: (waitSeconds + 10) * 1e3,
       signal
     });
   }
@@ -3779,7 +3824,7 @@ var HttpTransport = class {
     });
   }
   listCategories(params, signal) {
-    return this.call({ method: "GET", path: "/v1/categories", query: { match: params.match }, signal });
+    return this.call({ method: "GET", path: "/v1/categories", query: { ...params }, signal });
   }
   getCategory(categoryId, signal) {
     return this.call({ method: "GET", path: `/v1/categories/${encodeURIComponent(categoryId)}`, signal });
@@ -3835,6 +3880,9 @@ var HttpTransport = class {
       signal
     });
   }
+  learnReviewRule(reviewId, req, signal) {
+    return this.call({ method: "POST", path: `/v1/reviews/${encodeURIComponent(reviewId)}/learned-rules`, body: req, signal });
+  }
   saveRule(req, signal) {
     return this.call({
       method: "PUT",
@@ -4242,6 +4290,9 @@ var MockTransport = class {
   async getRules(params) {
     return this.backend.getRules(params);
   }
+  async learnReviewRule(reviewId, req) {
+    return this.backend.learnReviewRule(reviewId, req);
+  }
   async saveRule(req) {
     return this.backend.saveRule(req);
   }
@@ -5271,6 +5322,10 @@ var Rules = class {
   constructor(ctx) {
     this.ctx = ctx;
   }
+  /** Learn category or organization house rules from verified human review feedback. */
+  learnFromReview(reviewId, req, signal) {
+    return this.ctx.transport.learnReviewRule(reviewId, req, signal);
+  }
   /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
   get(params = {}, signal) {
     return this.ctx.transport.getRules(params, signal);
@@ -5278,8 +5333,8 @@ var Rules = class {
   /**
    * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
    * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
-   * key's project. Agents cannot author org-layer / house-style (`rule_layer:"org"`)
-   * rules in v1: that is a console/admin action.
+   * key's project. For all authenticated reviewer feedback use learnFromReview at the intended
+   * organization, project, or category scope. This method is project maintenance only.
    */
   save(req, signal) {
     return this.ctx.transport.saveRule(req, signal);
@@ -5556,7 +5611,7 @@ async function signWebhook(secret, body, timestampSeconds) {
 }
 
 // src/contract.ts
-var CONTRACT_VERSION = "0.1.0-pre.7";
+var CONTRACT_VERSION = "0.1.0-pre.9";
 var CONTRACT_MANIFEST = {
   name: "extrovert.review-loop",
   version: CONTRACT_VERSION,
@@ -5587,6 +5642,8 @@ var CONTRACT_MANIFEST = {
     // realtime (M3)
     "ReviewEventReason",
     "ReviewEventsResult",
+    "LearnReviewRuleRequest",
+    "LearnedReviewRule",
     "ReviewEventCursor",
     // chat / revision / restamp (M5/M7)
     "PostReviewChatRequest",