@makinbakin/sdk 0.0.1-rc.20 → 0.0.1-rc.21

package/_internal/core/plugin-types.d.ts

@@ -17,8 +17,8 @@
  * EventBus/ActivityAPI/PluginLogger, TaskLogEntry, …) ARE single-homed in the
  * SDK and re-exported below. Collapsing the boundary itself is WS2 work.
  */
-import type { ZodRawShape, ZodType } from 'zod';
-import type { ActivityAPI, EventBus, ExecToolResult, PluginHealthCheckInput, PluginLogger, SearchAPI, TaskLogEntry } from '@makinbakin/sdk/types';
+import type { z, ZodRawShape, ZodType } from 'zod';
+import type { ActivityAPI, ActivityClass, ConversationTurnsAPI, EventBus, ExecToolResult, HealthCheckRegistrationInput, HealthOwner, HealthRepairActionDefinition, PluginLogger, SearchAPI, TaskLogEntry } from '@makinbakin/sdk/types';
 import type { ContractStability, ContractVisibility, DocsExample, SchemaLike, SourceLocation } from './docs';
 import type { AgentRuntimeAdapter } from './adapters/runtime';
 import type { APIRoute as DeclarativeAPIRoute, PluginContextLite } from './routing/types';
@@ -33,18 +33,18 @@ export interface StorageAdapter {
     append(path: string, content: string): void;
     exists(path: string): boolean;
     readAll(): Record<string, string>;
-    list?(path?: string): string[];
-    remove?(path: string): void;
-    rename?(from: string, to: string): void;
-    stat?(path: string): {
+    list(path?: string): string[];
+    remove(path: string): void;
+    rename(from: string, to: string): void;
+    stat(path: string): {
         path: string;
         size: number;
         mtimeMs: number;
         isFile: boolean;
         isDirectory: boolean;
     } | null;
-    readJson?<T = unknown>(path: string): T | null;
-    writeJson?(path: string, value: unknown): void;
+    readJson<T = unknown>(path: string): T | null;
+    writeJson(path: string, value: unknown): void;
     /**
      * Convert a plugin-storage-relative path or glob to the content-dir-relative
      * path seen by file-backed search/watch APIs. Implementations never return
@@ -53,6 +53,7 @@ export interface StorageAdapter {
     searchPath?(path: string): string;
 }
 export type { EventBus } from '@makinbakin/sdk/types';
+export type NavSection = 'plan-and-automate' | 'create' | 'operations';
 export interface NavItem {
     id: string;
     label: string;
@@ -60,9 +61,17 @@ export interface NavItem {
     href: string;
     order?: number;
     children?: NavItem[];
-    alwaysExpanded?: boolean;
+    section?: NavSection;
 }
-export interface APIRoute {
+/**
+ * INTERNAL registered-route record — the erased shape routes take inside the
+ * plugin registry's state after declarative registration (typed schemas
+ * survive as extra fields the dispatcher reads). NOT a public authoring
+ * type: plugin authors declare routes with `defineRoute()` and the
+ * declarative-generic `APIRoute<C, P, Q, B>` from `@bakin/core/routing` /
+ * `@makinbakin/sdk` (audit 2026-07 H3 collapsed the two same-named types).
+ */
+export interface RegisteredAPIRoute {
     path: string;
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     handler: (req: Request, ctx: PluginContext) => Response | Promise<Response>;
@@ -76,6 +85,7 @@ export interface APIRoute {
     examples?: DocsExample[];
     source?: SourceLocation;
     permissions?: string[];
+    activityClass?: ActivityClass;
 }
 export interface UISlotRegistration {
     slot: string;
@@ -100,13 +110,15 @@ export interface PluginToolContext {
     activity: ActivityAPI;
     getSettings<T = Record<string, unknown>>(): T;
 }
-export interface ExecToolDefinition {
+export interface ExecToolDefinition<Shape extends ZodRawShape = ZodRawShape> {
     name: string;
     description: string;
     label?: string;
     activityDuplicate?: boolean;
-    parameters: ZodRawShape;
-    handler: (params: Record<string, unknown>, agent: string, ctx?: PluginToolContext) => Promise<ExecToolResult>;
+    activityClass?: ActivityClass;
+    parameters: Shape;
+    /** Params are inferred from `parameters` — declare the shape once, get typed params. */
+    handler: (params: z.infer<z.ZodObject<Shape>>, agent: string, ctx?: PluginToolContext) => Promise<ExecToolResult>;
     source?: string;
 }
 /** A skill that can be registered by plugins or loaded from disk */
@@ -204,7 +216,7 @@ export interface PluginNodeTypeInput<T = unknown> {
  * is prepended to `id` automatically (`{pluginId}.{id}`), matching the node-
  * type precedent. Built-in workflows-plugin runtime channels (general,
  * announcements, alerts, email) self-register at module load in
- * `plugins/workflows/lib/notification-channel-registry.ts`.
+ * `packages/core/src/workflows/notification-channel-registry.ts`.
  */
 export interface PluginNotificationChannelInput {
     id: string;
@@ -219,11 +231,18 @@ export interface NotificationChannelDef extends PluginNotificationChannelInput {
     /** Set when runtime === 'plugin'; identifies the owning plugin. */
     pluginId?: string;
 }
-export type { HealthCheckResult, HealthRepairSafety, HealthRepairChange, HealthRepairPlanItem, HealthRepairApplyResult, HealthRepairHandler, PluginHealthCheckInput, } from '@makinbakin/sdk/types';
-/** Core-internal: a registered plugin health check with its resolved owner. */
-export interface HealthCheckDef extends PluginHealthCheckInput {
-    runtime: 'plugin';
-    pluginId: string;
+export type { ActionIncidentInput, AdvisoryIncidentInput, CanonicalErrorObservation, CanonicalHealthyObservation, CanonicalUnknownObservation, CanonicalWarningObservation, ErrorObservationInput, HealthCheckExecution, HealthCheckRegistrationInput, HealthCheckRunContext, HealthCheckRunInput, HealthCheckSnapshot, HealthCheckState, HealthDisposition, HealthFullSweep, HealthGroup, HealthIncident, HealthIncidentInput, HealthInstructionsResolution, HealthNavigateResolution, HealthNonEmptyArray, HealthObservation, HealthObservationInput, HealthObservationStatus, HealthOwner, HealthOwnerKind, HealthRepairActionDefinition, HealthRepairApplyRequest, HealthRepairApplyResult, HealthRepairSafety, HealthRepairChange, HealthRepairPlanItem, HealthRepairPlan, HealthRepairPrecondition, HealthRepairResolution, HealthRepairTarget, HealthReport, HealthReportStatus, HealthReportSummary, HealthResolution, HealthResource, HealthResourceKind, HealthRerunResolution, HealthyObservationInput, JsonObject, JsonValue, SearchReadiness, SearchReadinessStage, SearchReadinessStageKey, SearchReadinessStatus, SearchStageStatus, UnknownObservationInput, WarningObservationInput, WatchIncidentInput, } from '@makinbakin/sdk/types';
+/** Core-internal canonical registration with its resolved owner and local id. */
+export interface HealthCheckDef extends HealthCheckRegistrationInput {
+    id: string;
+    localId: string;
+    owner: HealthOwner;
+}
+/** Core-internal canonical repair action with its resolved owner and local id. */
+export interface HealthRepairActionDef extends HealthRepairActionDefinition {
+    id: string;
+    localId: string;
+    owner: HealthOwner;
 }
 export interface PluginContext {
     storage: StorageAdapter;
@@ -233,25 +252,17 @@ export interface PluginContext {
     tasks: PluginTaskService;
     assets: AssetsAPI;
     registerNav(items: NavItem[]): void;
-    /**
-     * @deprecated Use `definePlugin({ routes: [defineRoute({...})] })` to declare
-     * routes. This adapter remains during the migration window for any
-     * out-of-tree plugin that still calls `ctx.registerRoute(...)` from
-     * `activate()`. In-repo plugins migrated in T6–T13 / T20 — none of them
-     * call this. The dispatcher adapts the legacy shape (input → body,
-     * output → responses[200]) when invoked through this path.
-     */
-    registerRoute(route: APIRoute): void;
     registerSlot(registration: UISlotRegistration): void;
-    registerExecTool(tool: ExecToolDefinition): void;
+    registerExecTool<Shape extends ZodRawShape>(tool: ExecToolDefinition<Shape>): void;
     registerSkill(skill: SkillDefinition): void;
     /**
      * Register a workflow definition shipped by this plugin. Disk-resident
      * user definitions in `~/.bakin/workflows/definitions/` always win on id
      * collision (user-wins). A second plugin claiming an id already taken by
-     * another plugin is a containment error: it's logged but does not throw
-     * out of `activate()`. Re-registering the same id from the same plugin
-     * is idempotent (newer wins) so hot reload works.
+     * another plugin THROWS out of `activate()` (R18 — the activation fails
+     * and the plugin's partial registrations are swept). Re-registering the
+     * same id from the same plugin is an update (newer wins) so hot reload
+     * works.
      */
     registerWorkflow(definition: WorkflowDefinitionInput, opts?: {
         readOnly?: boolean;
@@ -278,7 +289,9 @@ export interface PluginContext {
      * sweep — throws are isolated, a single bad check never crashes the
      * doctor. Returns the namespaced id.
      */
-    registerHealthCheck(def: PluginHealthCheckInput): string;
+    registerHealthCheck(def: HealthCheckRegistrationInput): string;
+    /** Register an owner-local repair action referenced by Health observations. */
+    registerHealthRepairAction(def: HealthRepairActionDefinition): string;
     watchFiles(patterns: string[]): void;
     /** Read this plugin's persisted settings */
     getSettings<T = Record<string, unknown>>(): T;
@@ -286,12 +299,14 @@ export interface PluginContext {
     updateSettings(patch: Record<string, unknown>): void;
     /** Structured activity logging */
     activity: ActivityAPI;
-    /** Plugin-scoped server log. Prefer this over console.* for lifecycle logs. */
-    log?: PluginLogger;
+    /** Plugin-scoped server log. Always provided; prefer over console.*. */
+    log: PluginLogger;
     /** Cross-plugin hook registration */
     hooks: HookAPI;
     /** Adapter-backed search — register content types, index, query */
     search: SearchAPI;
+    /** Shared conversation turn engine — background turns for chat-like surfaces (#703) */
+    conversations: ConversationTurnsAPI;
 }
 export type PluginTaskColumn = 'backlog' | 'todo' | 'inProgress' | 'review' | 'done' | 'blocked' | 'archived';
 export interface PluginTask {
@@ -310,6 +325,7 @@ export interface PluginTask {
     workflowId?: string;
     scheduleJobId?: string;
     projectId?: string;
+    brandId?: string;
     availableAt?: string;
     dueAt?: string;
     source?: PluginTaskSource;
@@ -334,6 +350,7 @@ export interface PluginTaskCreateInput {
     date?: string;
     workflowId?: string;
     projectId?: string;
+    brandId?: string;
     parentId?: string | null;
     availableAt?: string;
     dueAt?: string;
@@ -352,6 +369,7 @@ export interface PluginTaskUpdateInput {
     workflowId?: string;
     scheduleJobId?: string;
     projectId?: string;
+    brandId?: string;
     parentId?: string | null;
     availableAt?: string | null;
     dueAt?: string | null;
@@ -367,6 +385,7 @@ export interface PluginTaskService {
         column?: PluginTaskColumn;
         agent?: string;
         projectId?: string;
+        brandId?: string;
     }): Promise<PluginTask[]>;
     appendLog(id: string, entry: TaskLogEntry): Promise<void>;
 }
@@ -386,6 +405,9 @@ export interface AssetGenerationInfo {
         assetId: string;
         version: number;
     }>;
+    /** Brand provenance (#419): brand id + content fingerprint as-used. */
+    brandId?: string;
+    brandFingerprint?: string;
 }
 /** Create a new versioned asset (v1) from a source file. */
 export interface AssetCreateInput {
@@ -455,6 +477,23 @@ export interface AssetSummary {
     size: number;
     hasThumb: boolean;
 }
+/**
+ * Per-version detail of a versioned asset (mirrors the manifest's version
+ * entries — provenance fields are null when the version wasn't produced by a
+ * generation tool).
+ */
+export interface AssetVersionDetail {
+    version: number;
+    /** Version file name inside the asset directory (e.g. `v2.png`). */
+    file: string;
+    width: number | null;
+    height: number | null;
+    op: 'generate' | 'edit' | 'upload' | 'import';
+    tool: string | null;
+    prompt: string | null;
+    promptHash: string | null;
+    generation: AssetGenerationInfo | null;
+}
 export interface AssetsAPI {
     createAsset(input: AssetCreateInput): Promise<VersionedAssetRef>;
     /** Read an asset's current-version summary by id (metadata: type/description/tags/etc.), or null. */
@@ -465,8 +504,35 @@ export interface AssetsAPI {
         file: string;
     }>;
     resolveVersionFile(assetId: string, version?: number): Promise<AssetVersionFileRef | null>;
+    /** List asset summaries, optionally filtered by type and/or owning task. */
+    listAssets(filter?: {
+        type?: AssetTypeName;
+        taskId?: string;
+    }): Promise<AssetSummary[]>;
+    /** Read an asset's version history (current pointer + per-version detail), or null. */
+    getAssetVersions(assetId: string): Promise<{
+        currentVersion: number;
+        versions: AssetVersionDetail[];
+    } | null>;
+    /**
+     * Source-path-keyed upsert: create v1 if no asset tracks `sourcePath`,
+     * append a version if its content changed, or no-op if identical
+     * (`changed: false`). A path inside the asset store reflects to the asset
+     * it already belongs to — never a duplicate.
+     */
+    upsertFromSource(sourcePath: string, input: AssetCreateInput): Promise<VersionedAssetRef & {
+        changed: boolean;
+    }>;
+    /**
+     * Map an absolute path INSIDE the asset store back to its asset identity.
+     * `absPath` in the result is always the REAL version file (never the thumb).
+     * Null for anything outside the store or store-internal non-version files.
+     */
+    resolveStoreFile(absPath: string): Promise<(VersionedAssetRef & {
+        absPath: string;
+    }) | null>;
 }
-export type { SearchSchemaField, SearchIndexDefinition, SearchContentTypeDefinition, SearchQueryParams, SearchResult, SearchResponse, SearchHealthIndex, SearchHealthTable, SearchHealthSnapshot, SearchTransformOp, FilePatternMapper, FileBackedContentTypeDefinition, SearchAPI, SearchMaintenanceAPI, } from '@makinbakin/sdk/types';
+export type { SearchSchemaField, SearchIndexDefinition, SearchContentTypeDefinition, SearchQueryParams, SearchResult, SearchResponse, SearchHealthIndex, SearchHealthTable, SearchHealthSnapshot, SearchReindexItem, SearchTransformOp, SearchScanOptions, FilePatternMapper, FileBackedContentTypeDefinition, SearchAPI, SearchMaintenanceAPI, } from '@makinbakin/sdk/types';
 interface BaseSettingsField {
     key: string;
     label: string;
@@ -555,9 +621,6 @@ export interface BakinPlugin {
      * a bare `routes: APIRoute[]` annotation widens types and breaks the
      * per-route inference that drives the dispatcher's typed `parsed` argument.
      *
-     * Optional during the migration window (T1–T16); plugins still using
-     * `ctx.registerRoute(...)` from `activate()` continue to work via the
-     * dispatcher adapter.
      */
     routes?: ReadonlyArray<DeclarativeAPIRoute<PluginContextLite, any, any, any>>;
 }

package/_internal/core/routing/define.d.ts

@@ -8,6 +8,7 @@
  * from the schemas in the route literal.
  */
 import type { APIRoute, CoreContext, PluginContextLite } from './types';
+import type { ContentFile, NavItem, PluginSettingsSchema } from '../plugin-types';
 /**
  * Declare a plugin route. Handler `ctx` is bound to `PluginContextLite`. The
  * three generics (P/Q/B) are inferred from `params`, `query`, and `body`
@@ -19,16 +20,38 @@ export declare function defineRoute<P = undefined, Q = undefined, B = undefined>
  * Declare a core (host) route. Handler `ctx` is bound to `CoreContext`.
  */
 export declare function defineCoreRoute<P = undefined, Q = undefined, B = undefined>(route: APIRoute<CoreContext, P, Q, B>): APIRoute<CoreContext, P, Q, B>;
-/** Lower-bound shape every plugin definition must satisfy. */
+/**
+ * The exact shape a plugin definition may carry — the full `BakinPlugin`
+ * lifecycle surface plus declarative `routes`. Deliberately CLOSED (no index
+ * signature): a typo'd key (`settingSchema`, `onReadey`, …) fails typecheck
+ * at the `definePlugin` call site instead of silently doing nothing at
+ * runtime (audit 2026-07 H3).
+ */
 export interface DefinePluginInput {
     id: string;
     name: string;
     version: string;
     routes?: ReadonlyArray<APIRoute<PluginContextLite, any, any, any>>;
-    [key: string]: unknown;
+    activate(ctx: any): void | Promise<void>;
+    onReady?(): void | Promise<void>;
+    onShutdown?(): void | Promise<void>;
+    onSettingsChange?(settings: Record<string, unknown>): void | Promise<void>;
+    onUninstall?(ctx: any): void | Promise<void>;
+    settingsSchema?: PluginSettingsSchema;
+    navItems?: NavItem[];
+    contentFiles?: ContentFile[];
 }
 /**
  * Declare a plugin. Returns the input unchanged. Use this instead of a bare
  * `BakinPlugin` annotation so `routes` keeps per-element inference.
+ *
+ * The `& { [K in Exclude<...>]: never }` intersection is the exactness
+ * enforcement: `T extends DefinePluginInput` alone would structurally admit
+ * excess keys, so a typo'd `settingSchema` would compile and silently do
+ * nothing. With the intersection, any key outside `DefinePluginInput` must
+ * be `never` — which no real value satisfies — so typos fail at the call
+ * site (audit 2026-07 H3).
  */
-export declare function definePlugin<const T extends DefinePluginInput>(plugin: T): T;
+export declare function definePlugin<const T extends DefinePluginInput>(plugin: T & {
+    [K in Exclude<keyof T, keyof DefinePluginInput>]: never;
+}): T;

package/_internal/core/routing/dispatcher.d.ts

@@ -11,10 +11,11 @@
  *   - In dev / test, validate the response body against `responses[status]`
  *     and surface mismatches (test → throw, dev → console.warn).
  *
- * Adapter mapping: legacy `APIRoute.input` is treated as a JSON `body` schema
- * and legacy `APIRoute.output` is treated as `responses[200]`. This keeps
- * routes registered via the migration-window `ctx.registerRoute({...})` shim
- * flowing through the same validation path.
+ * There is no legacy `input`/`output` adapter mapping here: `ctx.registerRoute`
+ * and the legacy `APIRoute` shape were deleted (T19) — declarative routes and
+ * core routes are the only producers, and both speak `body`/`responses`.
+ * (The OpenAPI builder keeps a read-side mapping for historical doc callers;
+ * see packages/core/src/openapi/operation.ts.)
  */
 import { z } from 'zod';
 import type { BodySpec, ResponseSpec } from './types';
@@ -32,8 +33,6 @@ export interface DispatchableRoute {
     body?: BodySpec<unknown>;
     responses?: Partial<Record<string | number, ResponseSpec>>;
     handler: (req: Request, ctx: any, parsed?: any) => Response | Promise<Response>;
-    input?: z.ZodType<unknown>;
-    output?: z.ZodType<unknown>;
 }
 export interface DispatchInput {
     req: Request;
@@ -42,3 +41,13 @@ export interface DispatchInput {
     params: Record<string, string>;
 }
 export declare function dispatchRoute(input: DispatchInput): Promise<Response>;
+/**
+ * Loudly reject malformed `body` specs. A typo'd contentType (`'json'`)
+ * previously fell through parseBodySpec as a silent pass-through with an
+ * undefined parsed body — the handler then read `parsed.body.title` off
+ * undefined at request time with no hint why. Definition/registration time
+ * is the right place to fail: defineRoute/defineCoreRoute call this at
+ * module eval, and the plugin registry calls it for bare-literal routes at
+ * activation. `label` names the route in the error (e.g. `POST /items`).
+ */
+export declare function assertValidBodySpec(body: unknown, label: string): void;

package/_internal/core/routing/index.d.ts

@@ -10,6 +10,6 @@ export type { DefinePluginInput } from './define';
 export { RouteRegistry } from './registry';
 export type { RouteScope, RegisteredRoute, RouteMatch } from './registry';
 export { operationIdFor } from './operation-id';
-export { dispatchRoute } from './dispatcher';
+export { assertValidBodySpec, dispatchRoute } from './dispatcher';
 export type { DispatchInput } from './dispatcher';
 export { searchRoute } from './search-route';

package/_internal/core/routing/types.d.ts

@@ -2,17 +2,17 @@
  * Routing primitives — typed route contracts that drive runtime dispatch and
  * OpenAPI emission from a single source.
  *
- * The legacy `APIRoute` interface in `../plugin-types.ts` remains during the
- * migration window; this module's `APIRoute<C, P, Q, B>` is the new
- * declarative shape that plugins move to under T6–T16. The two coexist via the
- * `ctx.registerRoute` adapter wired in T4.
+ * The pure, context-free declarations (the generic `APIRoute`, body/response
+ * specs, `ParsedInput`) are DECLARED in `@makinbakin/sdk/types` (api-route.ts
+ * — a leaf module) and re-exported here bound to the core-tier
+ * `RouteContext`. That direction keeps the package DAG acyclic: core imports
+ * SDK types (as `plugin-types.ts` always has); the SDK never imports core
+ * from its types layer. Only the tier-specific route CONTEXTS live here.
  */
-import type { z } from 'zod';
-import type { ContractStability, ContractVisibility, DocsExample, SourceLocation } from '../docs';
+import type { APIRoute as SdkAPIRoute } from '@makinbakin/sdk/types';
 import type { AgentRuntimeAdapter } from '../adapters/runtime';
 import type { StorageAdapter, EventBus, SearchAPI, ActivityAPI, HookAPI, AssetsAPI, PluginTaskService } from '../plugin-types';
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-export type HttpStatus = 200 | 201 | 202 | 204 | 301 | 302 | 304 | 400 | 401 | 403 | 404 | 409 | 410 | 415 | 422 | 429 | 500 | 502 | 503 | 504;
+export type { HttpMethod, HttpStatus, JsonBodySpec, MultipartBodySpec, RawBodySpec, NoBodySpec, BodySpec, JsonResponseSpec, NoContentResponseSpec, NonJsonResponseSpec, ResponseSpec, ParsedInput, } from '@makinbakin/sdk/types';
 /**
  * Common surface every route handler can rely on, regardless of origin.
  * `PluginContext` and `CoreContext` extend this with their own additions.
@@ -46,69 +46,13 @@ export interface PluginContextLite extends RouteContext {
  * `packages/host/src/core-routes/`.
  */
 export type CoreContext = RouteContext;
-export interface JsonBodySpec<B = unknown> {
-    contentType: 'application/json';
-    schema: z.ZodType<B>;
-}
-export interface MultipartBodySpec<B = unknown> {
-    contentType: 'multipart/form-data';
-    schema?: z.ZodType<B>;
-}
-export interface RawBodySpec<B = unknown> {
-    contentType: '*/*';
-    schema?: z.ZodType<B>;
-}
-export interface NoBodySpec {
-    contentType: 'none';
-}
 /**
- * `body` declaration:
- *   - `z.ZodType` shorthand → JSON body validated against the schema.
- *   - explicit JSON spec → same, content-type stated.
- *   - multipart / raw → handler reads `req.formData()` / `req.body` itself.
- *   - none → dispatcher rejects non-empty bodies with 415.
- *
- * Omit the field entirely on routes that don't consume a body.
+ * Same declaration as `@makinbakin/sdk/types`' `APIRoute`, with the core-tier
+ * `RouteContext` as the default context. An alias (not a copy): the two are
+ * mutually assignable by construction — pinned in
+ * tests/core/plugin-type-contract.test.ts.
  */
-export type BodySpec<B = unknown> = z.ZodType<B> | JsonBodySpec<B> | MultipartBodySpec<B> | RawBodySpec<B> | NoBodySpec;
-export interface JsonResponseSpec {
-    contentType: 'application/json';
-    schema: z.ZodType;
-}
-export interface NoContentResponseSpec {
-    contentType: 'none';
-}
-export interface NonJsonResponseSpec {
-    contentType: 'text/event-stream' | 'text/html' | 'text/plain' | 'application/octet-stream' | 'image/png' | 'image/jpeg' | 'image/svg+xml' | (string & Record<never, never>);
-    schema?: z.ZodType;
-}
-export type ResponseSpec = z.ZodType | JsonResponseSpec | NoContentResponseSpec | NonJsonResponseSpec;
-/** Helper: `{ body: B }` if B is declared (non-undefined), else no fields. */
-type Field<K extends string, T> = [T] extends [undefined] ? unknown : {
-    [P in K]: T;
-};
-type Normalize<T> = {
-    [K in keyof T]: T[K];
-};
-export type ParsedInput<P, Q, B> = Normalize<Field<'params', P> & Field<'query', Q> & Field<'body', B>>;
-export interface APIRoute<C extends RouteContext = RouteContext, P = undefined, Q = undefined, B = undefined> {
-    path: string;
-    method: HttpMethod;
-    summary?: string;
-    description?: string;
-    params?: z.ZodType<P>;
-    query?: z.ZodType<Q>;
-    body?: P extends never ? never : BodySpec<B>;
-    responses?: Partial<Record<HttpStatus, ResponseSpec>>;
-    visibility?: ContractVisibility;
-    stability?: ContractStability;
-    permissions?: string[];
-    examples?: DocsExample[];
-    operationId?: string;
-    tags?: string[];
-    source?: SourceLocation;
-    handler: (req: Request, ctx: C, parsed: ParsedInput<P, Q, B>) => Response | Promise<Response>;
-}
+export type APIRoute<C extends RouteContext = RouteContext, P = undefined, Q = undefined, B = undefined> = SdkAPIRoute<C, P, Q, B>;
 /**
  * Subset of plugin metadata `definePlugin` cares about. The full `BakinPlugin`
  * interface lives in `../plugin-types.ts`; this declares the new fields the
@@ -120,4 +64,3 @@ export interface PluginWithRoutes {
     version: string;
     routes?: ReadonlyArray<APIRoute<PluginContextLite, any, any, any>>;
 }
-export {};

package/_internal/core/storage/atomic-write.d.ts

@@ -0,0 +1,11 @@
+export interface AtomicWriteOptions {
+    /** Append a trailing newline. Default true (pretty JSON convention). */
+    trailingNewline?: boolean;
+}
+/** Atomically write `text` to `path` (temp file + rename), creating parent dirs. */
+export declare function atomicWriteText(path: string, text: string): void;
+/**
+ * Atomically write `value` as pretty-printed JSON. Adds a trailing newline by
+ * default; pass `{ trailingNewline: false }` to match callers that wrote none.
+ */
+export declare function atomicWriteJson(path: string, value: unknown, opts?: AtomicWriteOptions): void;

package/_internal/core/tasks/store.d.ts

@@ -0,0 +1,129 @@
+import type { TaskLogEntry } from '@makinbakin/sdk/types';
+import type { Unsubscribe } from '../adapters/shared';
+export type { TaskLogEntry } from '@makinbakin/sdk/types';
+export interface BakinTask {
+    id: string;
+    title: string;
+    description?: string;
+    agent?: string;
+    /**
+     * Requested team assignment (#189). `team` alone = unresolved team task
+     * (the dispatch resolver picks a member); `team` + `agent` = resolved —
+     * team is retained so the record explains requested vs resolved.
+     * Exclusion semantics live in the app facade (src/core/task-store.ts).
+     */
+    team?: string;
+    createdBy?: string;
+    column: string;
+    order: number;
+    tags: string[];
+    workflowId?: string;
+    scheduleJobId?: string;
+    projectId?: string;
+    /** Brand link (#419) — resolved lazily at dispatch, mirrors projectId. */
+    brandId?: string;
+    /** Repo binding override (same-agent-concurrency D6): dispatch worktree target; project binding via projects.getRepo otherwise. */
+    repoPath?: string;
+    parentId?: string | null;
+    dependsOn?: string;
+    availableAt?: string;
+    dueAt?: string;
+    source?: TaskSource;
+    date?: string;
+    blockedReason?: string;
+    blockedBy: string[];
+    blocking: string[];
+    comments: TaskComment[];
+    pendingDelete: boolean;
+    log: TaskLogEntry[];
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Optimistic concurrency counter — bumped on every write. Absent on
+     * pre-upgrade tasks (treated as 0; lazy-stamped on the next write).
+     * API mutations may send expectedVersion and get a 409 when stale.
+     */
+    version?: number;
+}
+export interface TaskSource {
+    pluginId?: string;
+    entityType?: string;
+    entityId?: string;
+    purpose?: string;
+}
+export interface CreateBakinTaskInput {
+    id?: string;
+    title: string;
+    description?: string;
+    agent?: string;
+    team?: string;
+    createdBy?: string;
+    column?: string;
+    order?: number;
+    tags?: string[];
+    workflowId?: string;
+    scheduleJobId?: string;
+    projectId?: string;
+    brandId?: string;
+    /** Repo binding override (same-agent-concurrency D6): dispatch worktree target; project binding via projects.getRepo otherwise. */
+    repoPath?: string;
+    parentId?: string | null;
+    dependsOn?: string;
+    availableAt?: string;
+    dueAt?: string;
+    source?: TaskSource;
+}
+export type BakinTaskPatch = Partial<Pick<BakinTask, 'title' | 'description' | 'agent' | 'team' | 'createdBy' | 'column' | 'order' | 'tags' | 'workflowId' | 'scheduleJobId' | 'projectId' | 'brandId' | 'repoPath' | 'parentId' | 'dependsOn' | 'availableAt' | 'dueAt' | 'source' | 'date' | 'blockedReason' | 'blockedBy' | 'blocking' | 'pendingDelete'>>;
+export interface TaskListOpts {
+    column?: string;
+    agent?: string;
+    projectId?: string;
+    brandId?: string;
+    /** Repo binding override (same-agent-concurrency D6): dispatch worktree target; project binding via projects.getRepo otherwise. */
+    repoPath?: string;
+    includePendingDelete?: boolean;
+}
+export interface TaskComment {
+    id: string;
+    author: string;
+    body: string;
+    createdAt: string;
+}
+export interface TaskDependencyPatch {
+    blockedBy?: string[];
+    blocking?: string[];
+}
+export interface BakinTaskStoreEvent {
+    type: 'created' | 'updated' | 'deleted';
+    taskId: string;
+    task?: BakinTask;
+}
+export interface BakinTaskStore {
+    create(input: CreateBakinTaskInput): Promise<BakinTask>;
+    get(id: string): Promise<BakinTask | null>;
+    list(opts?: TaskListOpts): Promise<BakinTask[]>;
+    update(id: string, patch: BakinTaskPatch): Promise<BakinTask>;
+    move(id: string, column: string, order?: number): Promise<BakinTask>;
+    remove(id: string): Promise<void>;
+    appendLog(id: string, entry: TaskLogEntry): Promise<void>;
+    addComment(id: string, comment: TaskComment): Promise<void>;
+    setDependencies(id: string, deps: TaskDependencyPatch): Promise<BakinTask>;
+    markPendingDelete(id: string, pending: boolean): Promise<BakinTask>;
+    subscribe(handler: (event: BakinTaskStoreEvent) => void): Unsubscribe;
+}
+export interface SyncBakinTaskStore extends BakinTaskStore {
+    createSync(input: CreateBakinTaskInput): BakinTask;
+    getSync(id: string): BakinTask | null;
+    findSync(identifier: string): BakinTask | null;
+    listSync(opts?: TaskListOpts): BakinTask[];
+    updateSync(id: string, patch: BakinTaskPatch): BakinTask;
+    removeSync(id: string): void;
+    appendLogSync(id: string, entry: TaskLogEntry): void;
+    addCommentSync(id: string, comment: TaskComment): void;
+    setDependenciesSync(id: string, deps: TaskDependencyPatch): BakinTask;
+    markPendingDeleteSync(id: string, pending: boolean): BakinTask;
+    /** Index-backed column count (excludes pendingDelete, matching listSync). Zero file reads. */
+    countByColumnSync(column: string): number;
+}
+export declare function createEmptyBakinTask(input: CreateBakinTaskInput, now?: string): BakinTask;
+export declare function createFileBakinTaskStore(root: string): SyncBakinTaskStore;

package/_internal/core/tasks/testing.d.ts

@@ -0,0 +1,2 @@
+import type { BakinTask, BakinTaskStore } from './store';
+export declare function createMockBakinTaskStore(seed?: BakinTask[]): BakinTaskStore;

package/_internal/{plugins/workflows/lib → core/workflows}/notification-channel-registry.d.ts

@@ -8,7 +8,7 @@
  * here. Plugin ids are auto-namespaced as `{pluginId}.{id}` to avoid
  * cross-plugin collisions with the shared builtin ids.
  */
-import type { NotificationChannelDef, PluginNotificationChannelInput } from '../../../core/plugin-types';
+import type { NotificationChannelDef, PluginNotificationChannelInput } from '../plugin-types';
 export type { NotificationChannelDef, PluginNotificationChannelInput };
 export declare function registerNotificationChannel(def: NotificationChannelDef): void;
 export declare function getNotificationChannel(id: string): NotificationChannelDef | undefined;