target-supabase-sdk 0.2.3 → 0.2.5

package/dist/trigger/trigger-node.d.ts

@@ -12,6 +12,7 @@ import type { TriggerNodeOptions } from "./trigger.interface";
  */
 declare class TriggerNode extends BaseNodeRuntime {
     private readonly requireRunners;
+    private readonly loopIntervalMs;
     constructor(options?: TriggerNodeOptions);
     protected getLoopIntervalMs(): number;
     protected loopLoggerMinLevel(): LogLevel;

package/dist/trigger/trigger-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trigger-node.d.ts","sourceRoot":"","sources":["../../src/trigger/trigger-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAkB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAClG,OAAO,EAA6B,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D;;;;;;;;GAQG;AACH,cAAM,WAAY,SAAQ,eAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;gBAE7B,OAAO,CAAC,EAAE,kBAAkB;IAKxC,SAAS,CAAC,iBAAiB,IAAI,MAAM;IAIrC,SAAS,CAAC,kBAAkB,IAAI,QAAQ;cAIxB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;cA+B5D,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAc1F;AAED,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"trigger-node.d.ts","sourceRoot":"","sources":["../../src/trigger/trigger-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAkB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAClG,OAAO,EAA6B,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D;;;;;;;;GAQG;AACH,cAAM,WAAY,SAAQ,eAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,OAAO,CAAC,EAAE,kBAAkB;IAUxC,SAAS,CAAC,iBAAiB,IAAI,MAAM;IAIrC,SAAS,CAAC,kBAAkB,IAAI,QAAQ;cAIxB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;cA+B5D,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAc1F;AAED,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/trigger/trigger.constant.d.ts

@@ -1,5 +1,5 @@
 export declare const LOG_TOPIC_TRIGGER = "trigger";
-/** Fixed main-loop interval for {@link TriggerNode} (ms). */
+/** Default main-loop interval for {@link TriggerNode} when `loopIntervalMs` is omitted (ms). */
 export declare const TRIGGER_LOOP_INTERVAL_MS = 60000;
 /** Default extra retries after first failure within one runner tick. */
 export declare const TRIGGER_RUNNER_DEFAULT_RETRY_COUNT = 3;

package/dist/trigger/trigger.constant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trigger.constant.d.ts","sourceRoot":"","sources":["../../src/trigger/trigger.constant.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,wEAAwE;AACxE,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAEpD,sEAAsE;AACtE,eAAO,MAAM,qCAAqC,IAAI,CAAC"}
+{"version":3,"file":"trigger.constant.d.ts","sourceRoot":"","sources":["../../src/trigger/trigger.constant.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C,gGAAgG;AAChG,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,wEAAwE;AACxE,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAEpD,sEAAsE;AACtE,eAAO,MAAM,qCAAqC,IAAI,CAAC"}

package/dist/trigger/trigger.interface.d.ts

@@ -83,5 +83,15 @@ export interface TriggerNodeOptions {
      * Default `false` (warn and idle loop).
      */
     requireRunners?: boolean;
+    /**
+     * Main loop tick interval (ms). Runners are evaluated each tick; effective runner
+     * precision is bounded by this value. Default {@link TRIGGER_LOOP_INTERVAL_MS} (60s).
+     */
+    loopIntervalMs?: number;
+    /**
+     * Called after node logout, immediately before `process.exit`.
+     * Typical use: {@link unregisterServiceAtShutdown} for single-process L3 services.
+     */
+    beforeProcessExit?: () => void | Promise<void>;
 }
 //# sourceMappingURL=trigger.interface.d.ts.map

package/dist/trigger/trigger.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trigger.interface.d.ts","sourceRoot":"","sources":["../../src/trigger/trigger.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,oBAAY,eAAe;IACvB,OAAO,YAAY;CACtB;AAED,oBAAY,aAAa;IACrB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;CACpB;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;CAClD;AAED,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAElD,MAAM,WAAW,OAAQ,SAAQ,MAAM;IACnC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,eAAe,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAID,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,eAAe,CAAC;IACxB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAElF,MAAM,WAAW,4BAA4B;IACzC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,eAAe,CAAC;IACpB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B"}
+{"version":3,"file":"trigger.interface.d.ts","sourceRoot":"","sources":["../../src/trigger/trigger.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,oBAAY,eAAe;IACvB,OAAO,YAAY;CACtB;AAED,oBAAY,aAAa;IACrB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,MAAM,WAAW;CACpB;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,UAAU,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;CAClD;AAED,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAElD,MAAM,WAAW,OAAQ,SAAQ,MAAM;IACnC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,eAAe,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAID,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,eAAe,CAAC;IACxB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAElF,MAAM,WAAW,4BAA4B;IACzC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,eAAe,CAAC;IACpB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.3",
+    "version": "0.2.5",
     "description": "Supabase client initializer and data access APIs",
     "license": "MIT",
     "author": "KyLoc20",
@@ -47,7 +47,7 @@
     ],
     "scripts": {
         "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist', { recursive: true, force: true })\"",
-        "build": "pnpm clean && rollup -c && tsc -p tsconfig.dts.json && node scripts/verify-browser-entry.mjs",
+        "build": "pnpm clean && rollup -c && node --input-type=module -e \"console.log('[build] emitting declarations (tsc)...')\" && tsc -p tsconfig.dts.json && node scripts/verify-browser-entry.mjs",
         "typecheck": "tsc -p tsconfig.json --noEmit",
         "typecheck:scripts": "tsc -p tsconfig.scripts.json",
         "format": "biome check --write .",
@@ -56,6 +56,8 @@
         "worker:trigger": "tsx scripts/run-trigger-node.ts",
         "post-command": "tsx scripts/post-command.ts",
         "post-trigger": "tsx scripts/post-trigger.ts",
+        "seed:system-registry": "tsx scripts/seed-system-registry.ts",
+        "reset:system-registry": "tsx scripts/reset-system-registry.ts",
         "parcel:split": "tsx scripts/parcel-split-local.ts",
         "parcel:restore": "tsx scripts/parcel-restore-local.ts",
         "dev": "rollup -c --watch",

package/src/browser.ts

@@ -9,6 +9,24 @@ export type { SupabaseClient } from "@supabase/supabase-js";
 export * from "./core.api";
 export * from "./core.interface";
 export * from "./core.utils";
+export type {
+    GetExtractionPayload,
+    PatchExtractionObjectsPayload,
+    PostExtractionPayload,
+    ScanExtractionListPayload,
+} from "./extraction/extraction.api";
+export {
+    getExtraction,
+    getExtractionSchema,
+    patchExtractionObjects,
+    patchExtractionObjectsSchema,
+    postExtraction,
+    postExtractionSchema,
+    scanExtractionList,
+    scanExtractionListSchema,
+} from "./extraction/extraction.api";
+export type { Extraction, ExtractionDetails } from "./extraction/extraction.interface";
+export { CategoryExtraction } from "./extraction/extraction.interface";
 export * from "./idea/idea.interface";
 export * from "./link/link.api";
 export * from "./link/link.interface";
@@ -86,32 +104,88 @@ export * from "./repo/repo.interface";
 export type {
     Api,
     ApiDetails,
-    DiscoverServiceInput,
+    ClaimRegistrySlotInput,
+    Config,
+    ConfigDetails,
     GetApiPayload,
+    GetConfigPayload,
     GetServicePayload,
+    PatchServiceRuntimeInput,
     PostApiPayload,
+    PostServiceInstanceOptions,
     PostServicePayload,
+    PostSystemRegistryConfigPayload,
+    RegisterServiceInput,
+    RegistrySlotGuardResult,
+    RegistrySlotRuntimeState,
+    ReleasedRegistrySlot,
+    ReleaseSystemRegistrySlotsInput,
+    ReleaseSystemRegistrySlotsOutcome,
+    ResetSystemRegistryConfigPayload,
     Service,
+    ServiceBootstrapResult,
     ServiceDetails,
+    ServiceNodeSnapshot,
+    ServiceRegistrySession,
+    ServiceRuntime,
+    ServiceSlot,
+    SystemRegistrySeedSlot,
+    TargetSystemRegistrySlotView,
+    TargetSystemRegistryView,
 } from "./service/index";
 export {
     ApiMethod,
     apiDetailsSchema,
+    assertRegistrySlotAvailable,
+    assertRegistrySlotOwner,
+    buildEmptyServiceSlots,
+    buildSystemRegistryConfigDetails,
+    CategoryConfig,
     CategoryService,
-    discoverService,
+    claimServiceRegistrySlot,
+    createActiveServiceLifecycle,
+    createClaimedRegistrySlotRuntimeState,
+    DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS,
+    defaultL3ServiceDetails,
+    EMPTY_REGISTRY_SLOT_RUNTIME_STATE,
     fieldDefinitionSchema,
     getApi,
     getApiSchema,
+    getConfig,
+    getConfigSchema,
     getService,
     getServiceSchema,
+    getTargetSystemRegistry,
+    parseServiceSlot,
+    parseServiceSlots,
+    patchServiceRuntime,
     postApi,
     postApiSchema,
     postService,
+    postServiceInstance,
     postServiceSchema,
+    postSystemRegistryConfig,
+    postSystemRegistryConfigSchema,
+    registerService,
+    registerServiceAtStartup,
+    registrySlotRuntimePatchFromGuardResult,
+    releaseSystemRegistrySlots,
+    resetSystemRegistryConfig,
+    resetSystemRegistryConfigSchema,
+    resolveActiveRegistryServiceId,
+    runRegistrySlotGuardCheck,
     ServiceLifecycleStatus,
+    ServiceRegistryError,
+    ServiceSlotStatus,
     schemaDefinitionSchema,
     serviceDetailsSchema,
     serviceLifecycleSchema,
+    serviceNodeSnapshotSchema,
+    serviceRuntimeSchema,
+    systemRegistrySeedSlotSchema,
+    TARGET_SYSTEM_REGISTRY_KEY,
+    unregisterService,
+    unregisterServiceAtShutdown,
 } from "./service/index";
 export type { FetchInitFactory, FetchRetryOptions } from "./shared/http/fetch-retry";
 export {
@@ -120,9 +194,31 @@ export {
     isRetryableHttpStatus,
     requestHasBody,
 } from "./shared/http/fetch-retry";
-export type { CreateLoggerInput, LoggerWithScope, LogScope, LogScopePatch } from "./shared/log";
-export { createLogger, LogLevel, logManager } from "./shared/log";
+export type {
+    CreateLoggerInput,
+    DecodedLogBatch,
+    FlatLogEntry,
+    LogEntry,
+    LoggerWithScope,
+    LogScope,
+    LogScopePatch,
+} from "./shared/log";
+export {
+    createLogger,
+    decodeLogBatch,
+    decodeLogBatchList,
+    flattenLogBatch,
+    flattenLogBatches,
+    isLogBatchList,
+    isLogEntry,
+    LOG_BATCH_LOADER_KEY,
+    LOG_PERSIST_LOADER_KEY,
+    LogLevel,
+    logManager,
+    parseLogBatchMeta,
+} from "./shared/log";
 export { isHttpUrl, resolveFetchUrl } from "./shared/utils/fetch-url";
+export { getValueAtPath } from "./shared/utils/get-value-at-path";
 export type {
     ClassifiedNetworkError,
     FormatNetworkErrorOptions,
@@ -160,6 +256,8 @@ export {
 } from "./task/task.interface";
 export type { PostTaskPayload } from "./task/task-post.api";
 export { postTask, postTaskSchema } from "./task/task-post.api";
+export type { PostTaskWithRetryOptions, PostTaskWithRetryResult } from "./task/task-post-retry.api";
+export { POST_TASK_DEFAULT_MAX_ATTEMPTS, postTaskWithRetry } from "./task/task-post-retry.api";
 export type { TaskStatusCount } from "./task/task-queue";
 export { countTasksByType, summarizeTaskQueue } from "./task/task-queue";
 export * from "./word/word.interface";

package/src/extraction/extraction.api.ts

@@ -0,0 +1,232 @@
+import { z } from "zod";
+import {
+    createTarget,
+    getPossibleTarget,
+    getTarget,
+    isCreateTargetAlreadyExistsError,
+    type QueryFilter,
+    scanTargetList,
+    updateTargetDetails,
+    validateWithSchema,
+} from "../core.api";
+import type { SupabaseResponse } from "../core.interface";
+import { generateResponse } from "../core.interface";
+import { createLogger } from "../shared/log";
+import { CategoryExtraction, type Extraction, type ExtractionDetails } from "./extraction.interface";
+
+const targetIdSchema = z.string().trim().min(1);
+const loaderKeySchema = z.string().trim().min(1);
+
+export const postExtractionSchema = z.object({
+    name: z.string().trim().min(1),
+    /** Source Target id — for log analysis this is the producing Task id. */
+    sourceId: targetIdSchema,
+    loaderKey: loaderKeySchema,
+    meta: z.unknown().optional(),
+    objects: z.array(z.unknown()).min(1),
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+
+export type PostExtractionPayload = z.infer<typeof postExtractionSchema>;
+
+export const getExtractionSchema = z
+    .object({
+        id: targetIdSchema.optional(),
+        sourceId: targetIdSchema.optional(),
+        loaderKey: loaderKeySchema.optional(),
+    })
+    .refine(
+        (payload) => {
+            const hasId = payload.id != null && payload.id !== "";
+            const hasSource = payload.sourceId != null && payload.sourceId !== "";
+            if (hasId) {
+                return !hasSource;
+            }
+            return hasSource && payload.loaderKey != null && payload.loaderKey !== "";
+        },
+        { message: "Provide id, or both sourceId and loaderKey" },
+    );
+
+export type GetExtractionPayload = z.infer<typeof getExtractionSchema>;
+
+export const scanExtractionListSchema = z.object({
+    loaderKey: loaderKeySchema.optional(),
+    sourceId: targetIdSchema.optional(),
+    maxRows: z.number().int().min(1).max(500).optional(),
+    ascending: z.boolean().optional(),
+});
+
+export type ScanExtractionListPayload = z.infer<typeof scanExtractionListSchema>;
+
+export const patchExtractionObjectsSchema = z.object({
+    id: targetIdSchema,
+    objects: z.array(z.unknown()).min(1),
+    meta: z.unknown().optional(),
+    expectedRevision: z.number().int().min(0).optional(),
+});
+
+export type PatchExtractionObjectsPayload = z.infer<typeof patchExtractionObjectsSchema>;
+
+const extractionCategoryFilter: QueryFilter = {
+    field: "category",
+    operator: "eq",
+    value: CategoryExtraction.EXTRACTION,
+};
+
+function extractionRedundancyFilters(sourceId: string, loaderKey: string): QueryFilter[] {
+    return [
+        extractionCategoryFilter,
+        { field: "value", operator: "eq", value: sourceId },
+        { field: "details->>loaderKey", operator: "eq", value: loaderKey },
+    ];
+}
+
+function normalizeExtractionMeta(meta: unknown, patch?: unknown): Record<string, unknown> {
+    const base =
+        meta != null && typeof meta === "object" && !Array.isArray(meta)
+            ? { ...(meta as Record<string, unknown>) }
+            : {};
+    if (patch != null && typeof patch === "object" && !Array.isArray(patch)) {
+        Object.assign(base, patch as Record<string, unknown>);
+    }
+    const revision = typeof base.revision === "number" && Number.isInteger(base.revision) ? base.revision : 0;
+    base.revision = revision;
+    base.updatedAt = new Date().toISOString();
+    return base;
+}
+
+/** Create an Extraction row for `(sourceId, loaderKey)`. Idempotent on redundancy key. */
+export const postExtraction = validateWithSchema(
+    postExtractionSchema,
+    "postExtractionSchema",
+)(async (payload): Promise<SupabaseResponse<Extraction>> => {
+    const logger = createLogger({ module: "postExtraction" });
+    const meta = normalizeExtractionMeta(payload.meta, { revision: 0 });
+
+    try {
+        return await createTarget<Extraction, PostExtractionPayload>({
+            payload,
+            checkRedundancyFilterList: extractionRedundancyFilters(payload.sourceId, payload.loaderKey),
+            createFn: () => ({
+                name: payload.name,
+                value: payload.sourceId,
+                category: CategoryExtraction.EXTRACTION,
+                tagList: payload.tagList,
+                extra: payload.extra,
+                details: {
+                    manifestVersion: 0,
+                    loaderKey: payload.loaderKey,
+                    meta,
+                    objects: payload.objects,
+                },
+            }),
+        });
+    } catch (error) {
+        if (isCreateTargetAlreadyExistsError(error)) {
+            logger.warn("Extraction already exists for source + loaderKey", {
+                topic: "extraction",
+                data: { sourceId: payload.sourceId, loaderKey: payload.loaderKey },
+            });
+            throw error;
+        }
+        throw error;
+    }
+});
+
+/** Fetch one Extraction by row id, or by `(sourceId, loaderKey)`. */
+export const getExtraction = validateWithSchema(
+    getExtractionSchema,
+    "getExtractionSchema",
+)(async (payload): Promise<SupabaseResponse<Extraction>> => {
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList: [extractionCategoryFilter],
+        });
+        return {
+            ...result,
+            data: result.data as Extraction | undefined,
+        };
+    }
+
+    const result = await getPossibleTarget({
+        filterList: extractionRedundancyFilters(payload.sourceId!, payload.loaderKey!),
+    });
+
+    if (result.data == null) {
+        return generateResponse.error("Extraction not found", undefined, "NOT_FOUND") as SupabaseResponse<Extraction>;
+    }
+
+    return {
+        ...result,
+        data: result.data as Extraction,
+    };
+});
+
+/** Scan Extraction rows (newest first by default). */
+export const scanExtractionList = validateWithSchema(
+    scanExtractionListSchema,
+    "scanExtractionListSchema",
+)(async (payload) => {
+    const filterList: QueryFilter[] = [extractionCategoryFilter];
+    if (payload.loaderKey != null) {
+        filterList.push({ field: "details->>loaderKey", operator: "eq", value: payload.loaderKey });
+    }
+    if (payload.sourceId != null) {
+        filterList.push({ field: "value", operator: "eq", value: payload.sourceId });
+    }
+
+    return scanTargetList<Extraction>({
+        category: CategoryExtraction.EXTRACTION,
+        filterList,
+        maxRows: payload.maxRows ?? 100,
+        orderBy: { field: "created_at", ascending: payload.ascending ?? false },
+    });
+});
+
+/** Replace {@link ExtractionDetails.objects} and bump `meta.revision`. */
+export const patchExtractionObjects = validateWithSchema(
+    patchExtractionObjectsSchema,
+    "patchExtractionObjectsSchema",
+)(async (payload): Promise<SupabaseResponse<Extraction>> => {
+    const optimisticLockFilterList: QueryFilter[] = [];
+    if (payload.expectedRevision != null) {
+        optimisticLockFilterList.push({
+            field: "details->meta->>revision",
+            operator: "eq",
+            value: String(payload.expectedRevision),
+        });
+    }
+
+    try {
+        const data = await updateTargetDetails<Extraction, ExtractionDetails>({
+            id: payload.id,
+            optimisticLockFilterList,
+            updateFn: (current) => {
+                const currentMeta =
+                    current.meta != null && typeof current.meta === "object" && !Array.isArray(current.meta)
+                        ? (current.meta as Record<string, unknown>)
+                        : {};
+                const revision =
+                    typeof currentMeta.revision === "number" && Number.isInteger(currentMeta.revision)
+                        ? currentMeta.revision + 1
+                        : 1;
+                return {
+                    ...current,
+                    meta: normalizeExtractionMeta(current.meta, {
+                        ...(payload.meta != null && typeof payload.meta === "object" && !Array.isArray(payload.meta)
+                            ? payload.meta
+                            : {}),
+                        revision,
+                    }),
+                    objects: payload.objects,
+                };
+            },
+        });
+        return generateResponse.success(data as Extraction);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message, undefined, "PATCH_FAILED") as SupabaseResponse<Extraction>;
+    }
+});

package/src/extraction/extraction.interface.ts

@@ -0,0 +1,45 @@
+import type { Target } from "../core.interface";
+
+/**
+ * Interpretation layer for a source Target: pipeline output (systems, models, algorithms)
+ * materialized as structured data. Not a process (see Task) or raw bytes (see Parcel).
+ *
+ * @see `.cursor/skills/extraction/SKILL.md`
+ */
+export interface Extraction extends Target {
+    /** Human-readable label. */
+    name: string;
+    /**
+     * Source Target id — the single input this row interprets (any category).
+     * Immutable after create. Indexed for lookup: all Extractions where `value = sourceId`.
+     * Not a dedup hash or pipeline run id.
+     */
+    value: string;
+    category: CategoryExtraction;
+    details: ExtractionDetails;
+}
+
+export enum CategoryExtraction {
+    EXTRACTION = "extraction",
+}
+
+export interface ExtractionDetails {
+    manifestVersion: 0;
+    /**
+     * Extractor identifier. Together with {@link Extraction.value} (source id) forms the
+     * logical unique key: one Extraction row per `(sourceTargetId, loaderKey)`.
+     * Determines how to parse and render {@link objects} (Extractor-owned schema).
+     */
+    loaderKey: string;
+    /**
+     * Extractor-owned metadata for this interpretation (e.g. revision, updatedAt, pipeline).
+     * Updated alongside {@link objects}; kept `unknown` at SDK boundary — see Extractor module.
+     */
+    meta: unknown;
+    /**
+     * Latest mutable analysis results for this source + Extractor — not an immutable snapshot.
+     * Shape is defined by the Extractor for {@link loaderKey}; SDK keeps `unknown[]` at core.
+     * Large payloads should reference Parcel (or similar) rather than inline in this array.
+     */
+    objects: Array<unknown>;
+}

package/src/list/list.interface.ts

@@ -13,8 +13,8 @@ export interface List extends Target {
 
 export interface ListDetails {
     manifestVersion: number;
-    /** If string, it is the meta brief of the list, TODO */
-    meta: string;
+    /** Optional list metadata (shape depends on `loaderKey`). */
+    meta: unknown;
     /** If string, it is the url of the preview TODO */
     preview: string;
     /** How to render the List */

package/src/node/fs/json-state-store.ts

@@ -76,8 +76,11 @@ export function createJsonFileStateStore<T extends object, NK extends keyof T =
                 const raw = await readFile(filePath, "utf8");
                 const parsed = JSON.parse(raw) as Partial<T>;
                 return mergeWithNested(defaultState, parsed, {}, nestedKeys);
-            } catch {
-                return { ...defaultState };
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+                    return mergeWithNested(defaultState, {}, {}, nestedKeys);
+                }
+                throw error;
             }
         },
 

package/src/node/fs/runtime-state-path.ts

@@ -0,0 +1,35 @@
+import { dirname, join } from "node:path";
+
+const RUNTIME_STATE_SHARD_DIR = "runtime-state";
+
+export interface ResolvedRuntimeStatePaths {
+    /** Directory holding one JSON file per top-level slice. */
+    stateDir: string;
+    /** Legacy monolithic `state.json` — migrated on read/reset when present. */
+    legacyFilePath: string | null;
+}
+
+/**
+ * Resolve sharded runtime state layout from {@link CreateServiceRuntimeStateStoreOptions.filePath}.
+ *
+ * | `filePath`              | Shard dir                         | Legacy        |
+ * |-------------------------|-----------------------------------|---------------|
+ * | `.../state.json`        | `.../runtime-state/`              | `state.json`  |
+ * | `.../runtime-state/`    | same directory                    | none          |
+ */
+export function resolveRuntimeStatePaths(filePath: string): ResolvedRuntimeStatePaths {
+    if (filePath.endsWith(".json")) {
+        return {
+            stateDir: join(dirname(filePath), RUNTIME_STATE_SHARD_DIR),
+            legacyFilePath: filePath,
+        };
+    }
+    return {
+        stateDir: filePath,
+        legacyFilePath: null,
+    };
+}
+
+export function runtimeStateShardPath(stateDir: string, sliceKey: string): string {
+    return join(stateDir, `${sliceKey}.json`);
+}