@nodetool-ai/node-sdk 0.7.0-rc.23 → 0.8.2

package/dist/registry.d.ts

@@ -1,14 +1,22 @@
-import type { NodeDescriptor } from "@nodetool-ai/protocol";
+import type { GraphData, HydratedGraphData, NodeDescriptor, Platform } from "@nodetool-ai/protocol";
 import type { NodeExecutor, ResolvedNodeType } from "@nodetool-ai/kernel";
 import type { NodeClass } from "./base-node.js";
 import type { NodeMetadata, PythonMetadataLoadOptions, PythonMetadataLoadResult } from "./metadata.js";
 import type { NodePropertyValidationIssue } from "./validation.js";
+import type { ScoredNode, ScoreOptions } from "./search.js";
 export interface NodeRegistryOptions {
     metadataByType?: Map<string, NodeMetadata>;
     strictMetadata?: boolean;
 }
+export type NodeMetadataSource = "typescript" | "python-package" | "python-bridge" | "loaded-metadata";
 export interface RegisterNodeOptions {
     metadata?: NodeMetadata;
+    source?: NodeMetadataSource;
+    packageId?: string;
+}
+export interface LoadMetadataOptions {
+    source?: NodeMetadataSource;
+    packageId?: string;
 }
 export interface RegistryGraphResolverOptions {
     loadNamespace?: (namespace: string, registry: NodeRegistry) => Promise<void> | void;
@@ -17,9 +25,35 @@ export declare class NodeRegistry {
     private _classes;
     private _loadedMetadataByType;
     private _registeredMetadataByType;
+    private _loadedMetadataSourceByType;
+    private _registeredMetadataSourceByType;
+    private _loadedPackageIdByType;
+    private _registeredPackageIdByType;
+    private _activePackageId;
     private _strictMetadata;
+    private _revision;
+    private _mergedMetadataCache;
+    private _searchIndexCache;
     constructor(options?: NodeRegistryOptions);
     register(nodeClass: NodeClass, options?: RegisterNodeOptions): void;
+    /**
+     * Drop the memoized metadata array and search index. Called by every
+     * mutation so the next read rebuilds from the current maps.
+     */
+    private invalidateMetadataCaches;
+    /**
+     * Attribute synchronous registrar calls to an explicit package identity.
+     * Package registration functions are synchronous by contract.
+     */
+    registerPackage(packageId: string, registrar: (registry: NodeRegistry) => void): void;
+    /** Monotonic metadata revision used to invalidate derived contract caches. */
+    get revision(): number;
+    /**
+     * Merged metadata for every node (loaded Python metadata first, registered TS
+     * metadata last so a TS class wins on a node_type collision). Built once and
+     * memoized; callers that mutate the result must copy it first.
+     */
+    private mergedMetadata;
     /**
      * Validate a node descriptor against its registered class's @prop schema.
      *
@@ -34,21 +68,90 @@ export declare class NodeRegistry {
      * reference to the registry itself.
      */
     createNodeValidator(): (descriptor: NodeDescriptor, connectedHandles: ReadonlySet<string>) => NodePropertyValidationIssue[];
+    /**
+     * Return a new NodeRegistry containing only the node classes that declare
+     * support for `target`. Loaded (Python) metadata is copied across when the
+     * matching class is included.
+     *
+     * Used at bundle / deployment time to construct a registry tailored to the
+     * active platform — the workflow runner then naturally fails on any graph
+     * referencing an unsupported node type.
+     */
+    forPlatform(target: Platform): NodeRegistry;
+    /**
+     * Validator that rejects nodes not supporting `target`. Compose with
+     * {@link createNodeValidator} when enforcing platform constraints in a
+     * registry that contains nodes for multiple platforms.
+     */
+    createPlatformValidator(target: Platform): (descriptor: NodeDescriptor, connectedHandles: ReadonlySet<string>) => NodePropertyValidationIssue[];
     resolve(descriptor: NodeDescriptor): NodeExecutor;
     getClass(nodeType: string): NodeClass | undefined;
     has(nodeType: string): boolean;
     list(): string[];
     getMetadata(nodeType: string): NodeMetadata | undefined;
+    getMetadataSource(nodeType: string): NodeMetadataSource | undefined;
+    /**
+     * Exact package identity recorded by the loader or registrar for this node.
+     * Undefined means package provenance is not authoritative.
+     */
+    getNodePackageId(nodeType: string): string | undefined;
+    /** Exact package identities represented by the current registry. */
+    listNodePackageIds(): string[];
     resolveMetadata(nodeType: string): NodeMetadata | undefined;
     listMetadata(): NodeMetadata[];
+    /**
+     * Rank registered nodes against `terms` using a memoized search index.
+     *
+     * Equivalent to `rankNodeMetadata(this.listMetadata(), terms, options)` but
+     * reuses a precomputed index across calls — the planner's inner loop. The
+     * index is invalidated whenever the registry changes.
+     */
+    searchMetadata(terms: readonly string[], options?: ScoreOptions): ScoredNode[];
     listRegisteredNodeTypesWithoutMetadata(): string[];
     /** Add or replace metadata for a node type (e.g. from Python bridge). */
-    loadMetadata(nodeType: string, metadata: NodeMetadata): void;
+    loadMetadata(nodeType: string, metadata: NodeMetadata, options?: LoadMetadataOptions): void;
     loadPythonMetadata(options?: PythonMetadataLoadOptions): PythonMetadataLoadResult;
+    /**
+     * Remove a node type from the registry.
+     * Returns true if the node type was present and removed.
+     */
+    unregister(nodeType: string): boolean;
     clear(): void;
     static readonly global: NodeRegistry;
 }
 export declare function register(nodeClass: NodeClass): void;
+/**
+ * Stamp streaming/control flags from the registry onto graph descriptors.
+ * Graphs arriving from a client carry only `type` and `properties`, and the
+ * kernel actor trusts `node.is_streaming_input` to pick run() over a one-shot
+ * process() — without this every streaming node "completes" instantly with
+ * empty outputs. The full-fat equivalent (which also resolves property/output
+ * types and drops unknown node types) is `Graph.loadFromDict` with
+ * `createGraphNodeTypeResolver`; this is the lightweight synchronous version
+ * for runners that only need correct execution semantics.
+ *
+ * Flags are resolved from the node's registered TS class when present, else
+ * from its loaded metadata (Python nodes have no TS class — they live only as
+ * metadata loaded from the worker's `package_metadata`, so `getClass` returns
+ * undefined and we must consult `resolveMetadata` or a streaming Python node
+ * read from a saved graph silently runs one-shot). This mirrors
+ * `Graph.loadFromDict`, which already reads the Python flag from metadata.
+ * `is_streaming_output` is derived from a TS class via `hasStreamingOutput`
+ * (purely structural: a `genProcess` override or iteration/forward/chunk
+ * correlation — ForEach, Collection, RepeatCount), and from the metadata's
+ * already-resolved boolean otherwise. Node types the registry doesn't know at
+ * all keep their own flags, defaulted to false (resolveExecutor reports
+ * unknown types loudly).
+ */
+export declare function hydrateGraphNodeFlags(graph: GraphData, registry: Pick<NodeRegistry, "getClass" | "resolveMetadata">): HydratedGraphData;
+/**
+ * The declared input types of one node type, as a `propertyTypes`-shaped map
+ * (`{[property]: "list[image]" | "str" | …}`). This is the kernel's authority
+ * on list-ness — correlation analysis and multi-edge fan-in read it — so
+ * hydration paths that do not go through `Graph.loadFromDict` stamp it from
+ * here rather than re-deriving the rendering.
+ */
+export declare function propertyTypesForMetadata(metadata: NodeMetadata): Record<string, string>;
 export declare function createGraphNodeTypeResolver(registry: NodeRegistry, options?: RegistryGraphResolverOptions): {
     resolveNodeType: (nodeType: string) => Promise<ResolvedNodeType | null>;
 };

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EACV,YAAY,EACZ,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,CACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,YAAY,KACnB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,qBAAqB,CAAmC;IAChE,OAAO,CAAC,yBAAyB,CAAmC;IACpE,OAAO,CAAC,eAAe,CAAU;gBAErB,OAAO,GAAE,mBAAwB;IAS7C,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI;IAqBvE;;;;;;OAMG;IACH,YAAY,CACV,UAAU,EAAE,cAAc,EAC1B,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,GAC7D,2BAA2B,EAAE;IAWhC;;;;OAIG;IACH,mBAAmB,IAAI,CACrB,UAAU,EAAE,cAAc,EAC1B,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,KAClC,2BAA2B,EAAE;IAKlC,OAAO,CAAC,UAAU,EAAE,cAAc,GAAG,YAAY;IAgBjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIjD,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9B,IAAI,IAAI,MAAM,EAAE;IAIhB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAOvD,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAS3D,YAAY,IAAI,YAAY,EAAE;IAc9B,sCAAsC,IAAI,MAAM,EAAE;IAMlD,yEAAyE;IACzE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IAI5D,kBAAkB,CAChB,OAAO,GAAE,yBAA8B,GACtC,wBAAwB;IAQ3B,KAAK,IAAI,IAAI;IAMb,MAAM,CAAC,QAAQ,CAAC,MAAM,eAAsB;CAC7C;AAED,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAEnD;AAoBD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,4BAAiC,GACzC;IAAE,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;CAAE,CA2D7E"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}