@granular-software/sdk 0.4.26 → 0.4.28

package/dist/cli/index.js

@@ -13114,10 +13114,15 @@ external_exports.union([
     scalarType: external_exports.string().optional()
   }).strict()
 ]);
+external_exports.union([
+  external_exports.boolean(),
+  external_exports.object({
+    enabled: external_exports.boolean().optional(),
+    phonetic: external_exports.boolean().optional()
+  }).strict()
+]);
 external_exports.object({
-  operator: external_exports.enum(
-    [...VALIDATION_RULE_OPERATORS]
-  ),
+  operator: external_exports.enum([...VALIDATION_RULE_OPERATORS]),
   stringValue: external_exports.string().optional(),
   numberValue: external_exports.number().optional(),
   booleanValue: external_exports.boolean().optional(),
@@ -13210,12 +13215,18 @@ function collectMetamodelSummarySelections(packages) {
   const propertyFields = [];
   const methodFields = [];
   for (const metamodelPackage of packages) {
-    pushUnique(classFields, metamodelPackage.summary.selections?.classFields || []);
+    pushUnique(
+      classFields,
+      metamodelPackage.summary.selections?.classFields || []
+    );
     pushUnique(
       propertyFields,
       metamodelPackage.summary.selections?.propertyFields || []
     );
-    pushUnique(methodFields, metamodelPackage.summary.selections?.methodFields || []);
+    pushUnique(
+      methodFields,
+      metamodelPackage.summary.selections?.methodFields || []
+    );
   }
   return {
     classFields: unique(classFields),
@@ -13303,7 +13314,11 @@ function createMetamodelRegistry(metamodelPackages) {
       return collectMetamodelSummarySelections(packages);
     },
     applyClassSummaryReaders(rawClass, classSummary) {
-      return applyMetamodelSummaryReadersToClass(packages, rawClass, classSummary);
+      return applyMetamodelSummaryReadersToClass(
+        packages,
+        rawClass,
+        classSummary
+      );
     },
     applyPropertySummaryReaders(rawProperty, propertySummary) {
       return applyMetamodelSummaryReadersToProperty(
@@ -13313,7 +13328,11 @@ function createMetamodelRegistry(metamodelPackages) {
       );
     },
     applyMethodSummaryReaders(rawMethod, methodSummary) {
-      return applyMetamodelSummaryReadersToMethod(packages, rawMethod, methodSummary);
+      return applyMetamodelSummaryReadersToMethod(
+        packages,
+        rawMethod,
+        methodSummary
+      );
     },
     applyClassIR(classIR, classSummary) {
       return applyMetamodelClassIR(packages, classIR, classSummary);
@@ -13361,6 +13380,10 @@ function mergeClassSummaryPatch(target, patch) {
 }
 function mergePropertySummaryPatch(target, patch) {
   pushUnique(target.notes, patch.notes || []);
+  if (patch.searchable !== void 0) target.searchable = patch.searchable;
+  if (patch.searchablePhonetic !== void 0) {
+    target.searchablePhonetic = patch.searchablePhonetic;
+  }
   if (patch.required !== void 0) target.required = patch.required;
   if (patch.enumRule !== void 0) target.enumRule = patch.enumRule;
   if (patch.filterBy !== void 0) target.filterBy = patch.filterBy;
@@ -13372,9 +13395,11 @@ function mergeMethodSummaryPatch(target, patch) {
   if (patch.effectKey !== void 0) target.effectKey = patch.effectKey;
   if (patch.description !== void 0) target.description = patch.description;
   if (patch.inputSchema !== void 0) target.inputSchema = patch.inputSchema;
-  if (patch.outputSchema !== void 0) target.outputSchema = patch.outputSchema;
+  if (patch.outputSchema !== void 0)
+    target.outputSchema = patch.outputSchema;
   if (patch.metamodels !== void 0) target.metamodels = patch.metamodels;
-  if (patch.effectBehaviors !== void 0) target.effectBehaviors = patch.effectBehaviors;
+  if (patch.effectBehaviors !== void 0)
+    target.effectBehaviors = patch.effectBehaviors;
   if (patch.static !== void 0) target.static = patch.static;
 }
 function toPascalCase2(value) {
@@ -13777,12 +13802,20 @@ function defaultFilterOperators(scalarType) {
   switch ((scalarType || "").toLowerCase()) {
     case "number":
     case "date":
-      return ["equal_to", "greater_than", "less_than", "not_null"];
+      return [
+        "equal_to",
+        "greater_than",
+        "greater_than_or_equal_to",
+        "less_than",
+        "less_than_or_equal_to",
+        "not_null"
+      ];
     case "boolean":
-      return ["equal_to", "not_null"];
+      return ["equal_to", "true", "false", "not_null"];
     default:
       return [
         "equal_to",
+        "in",
         "contains",
         "not_contains",
         "starts_with",
@@ -13791,16 +13824,26 @@ function defaultFilterOperators(scalarType) {
       ];
   }
 }
+function supportsDefaultFilterBy(scalarType) {
+  return ["string", "number", "boolean", "date"].includes(
+    String(scalarType || "").toLowerCase()
+  );
+}
 function normalizeFilterByInput(filterBy, scalarType) {
-  if (!filterBy) return null;
+  if (filterBy === false) return null;
+  if (filterBy === void 0) {
+    if (!supportsDefaultFilterBy(scalarType)) return null;
+    return { operators: defaultFilterOperators(scalarType), scalarType };
+  }
   if (filterBy === true) {
-    return { operators: defaultFilterOperators(scalarType) };
+    return { operators: defaultFilterOperators(scalarType), scalarType };
   }
   if (Array.isArray(filterBy)) {
-    return { operators: filterBy };
+    return { operators: filterBy, scalarType };
   }
   return {
-    operators: filterBy.operators
+    operators: filterBy.operators,
+    scalarType: filterBy.scalarType || scalarType
   };
 }
 function buildFilterByFieldMutations(fieldPath, filterBy, scalarType) {
@@ -13811,7 +13854,7 @@ function buildFilterByFieldMutations(fieldPath, filterBy, scalarType) {
       label: `set filterBy on ${fieldPath}`,
       query: `mutation { at(path: ${JSON.stringify(fieldPath)}) { set_filter_by(operators: ${JSON.stringify(
         normalized.operators
-      )}) { operators } } }`
+      )}${normalized.scalarType ? `, scalar_type: ${JSON.stringify(normalized.scalarType)}` : ""}) { operators } } }`
     }
   ];
 }
@@ -13821,7 +13864,7 @@ var filterByMetamodelPackage = defineMetamodelPackage({
     fieldRows: [
       {
         key: "filterBy",
-        description: "Exposes filter operators for generated query surfaces. Accepts `true`, an operator array, or `{ operators, scalarType }`."
+        description: "Exposes filter operators for generated query surfaces. Scalar fields are filterable by default; set `filterBy: false` to opt out, or override with `true`, an operator array, or `{ operators, scalarType }`."
       }
     ]
   },
@@ -14085,6 +14128,123 @@ var requiredMetamodelPackage = defineMetamodelPackage({
   }
 });
 
+// ../metamodel-searchable/src/index.ts
+function supportsDefaultSearchable(scalarType) {
+  return String(scalarType || "").toLowerCase() === "string";
+}
+function normalizeSearchableInput(searchable, scalarType) {
+  if (!supportsDefaultSearchable(scalarType)) return null;
+  if (typeof searchable === "boolean" || searchable === void 0) {
+    return {
+      enabled: searchable !== false,
+      phonetic: false
+    };
+  }
+  const enabled = searchable.enabled !== false;
+  return {
+    enabled,
+    phonetic: enabled && searchable.phonetic === true
+  };
+}
+function buildSearchableFieldMutations(fieldPath, searchable, scalarType) {
+  const normalized = normalizeSearchableInput(searchable, scalarType);
+  if (normalized === null) return [];
+  return [
+    {
+      label: `set searchable on ${fieldPath}`,
+      query: `mutation { at(path: ${JSON.stringify(fieldPath)}) { set_searchable(enabled: ${normalized.enabled}, phonetic: ${normalized.phonetic}) { enabled phonetic } } }`
+    }
+  ];
+}
+var searchableMetamodelPackage = defineMetamodelPackage({
+  id: "searchable",
+  docs: {
+    fieldRows: [
+      {
+        key: "searchable",
+        description: "Controls full-text search exposure for string fields. String fields are searchable by default; set `searchable: false` to opt out, or use `searchable: { phonetic: true }` to keep the field searchable while enabling FalkorDB phonetic matching for class-wide search."
+      }
+    ]
+  },
+  graphql: {
+    typeDefs: [
+      `
+      type SearchableMetamodel {
+        model: Model!
+        enabled: Boolean!
+        phonetic: Boolean!
+      }
+
+      extend type Model {
+        searchable: SearchableMetamodel
+      }
+
+      extend type ModelMutation {
+        set_searchable(enabled: Boolean!, phonetic: Boolean): SearchableMetamodel
+      }
+      `
+    ],
+    createResolvers({ run }) {
+      return {
+        SearchableMetamodel: {
+          model: (value) => value.model,
+          enabled: (value) => value.enabled !== false,
+          phonetic: (value) => value.phonetic === true
+        },
+        Model: {
+          searchable: async (ant) => await run(ant.searchable())
+        },
+        ModelMutation: {
+          set_searchable: async (ant, { enabled, phonetic }) => {
+            return {
+              model: await run(ant.set_searchable(enabled, phonetic === true)),
+              enabled,
+              phonetic: phonetic === true
+            };
+          }
+        }
+      };
+    }
+  },
+  manifest: {
+    buildFieldMutations(fieldPath, spec) {
+      return buildSearchableFieldMutations(
+        fieldPath,
+        spec.searchable,
+        spec.type
+      );
+    }
+  },
+  summary: {
+    selections: {
+      propertyFields: [`searchable { enabled phonetic }`]
+    },
+    readPropertySummary(rawProperty) {
+      if (typeof rawProperty.searchable?.enabled !== "boolean") {
+        return {};
+      }
+      return {
+        searchable: rawProperty.searchable.enabled,
+        searchablePhonetic: rawProperty.searchable.phonetic === true
+      };
+    }
+  },
+  domain: {
+    applyToPropertyIR(propertyIR, propertySummary) {
+      if (String(propertySummary.type || "").toLowerCase() !== "string" || propertySummary.searchable === false) {
+        return propertyIR;
+      }
+      return {
+        ...propertyIR,
+        docs: [
+          ...propertyIR.docs,
+          propertySummary.searchablePhonetic ? "Searchable via `search` using FalkorDB full-text query syntax with phonetic matching enabled." : "Searchable via `search` using FalkorDB full-text query syntax."
+        ]
+      };
+    }
+  }
+});
+
 // ../metamodel-state-machine/src/index.ts
 function normalizeStateMachines(values) {
   return (values || []).map((machine) => {
@@ -14665,6 +14825,7 @@ var DEFAULT_METAMODEL_PACKAGES = [
   requiredMetamodelPackage,
   enumMetamodelPackage,
   filterByMetamodelPackage,
+  searchableMetamodelPackage,
   validationRuleMetamodelPackage,
   stateMachineMetamodelPackage,
   effectBehaviorsMetamodelPackage
@@ -14838,6 +14999,7 @@ Scalar fields can carry lightweight metamodels directly in their field spec:
       "type": "string",
       "required": true,
       "note": "Must use the canonical prefix",
+      "searchable": { "phonetic": true },
       "filterBy": true,
       "validate": [
         { "operator": "regex", "stringValue": "^TKT-[A-Z0-9-]+$" }
@@ -14858,11 +15020,27 @@ Scalar fields can carry lightweight metamodels directly in their field spec:
         { "operator": "gt", "numberValue": 0 },
         { "operator": "lt", "numberValue": 100 }
       ]
+    },
+    "internal_code": {
+      "type": "string",
+      "description": "Opaque implementation detail",
+      "searchable": false,
+      "filterBy": false
     }
   }
 }
 \`\`\`
 
+Scalar fields are filterable by default. Set \`"filterBy": false\` only when a field should not appear in generated filter surfaces.
+String fields are searchable by default. Set \`"searchable": false\` only when a field should be excluded from generated full-text search surfaces and heavy full-text indexes.
+\`search\` is broad class-wide retrieval across all searchable string fields of a class. It is not a field-scoped operator. Use \`filter\` for exact field-specific constraints, and combine \`search\` + \`filter\` when you need both flexible text matching and exact structure.
+Runtime note: class-wide \`search\` is implemented as one denormalized full-text search document per class instance, built from that instance's searchable string fields. Exact field constraints still belong in \`filter\`.
+Preferred search ladder: start with plain text such as \`find({ search: "example name" })\`. If results are empty or ambiguous, retry with RediSearch-style fuzzy / prefix / OR operators. Add \`filter\` only when you need exact structural narrowing.
+Plain string \`search\` is normalized for human text before it reaches full-text search, so case, punctuation, repeated whitespace, and diacritics do not need to be manually enumerated in agent code.
+Do not manually enumerate capitalization / punctuation / spacing variants in agent code. Use plain \`search\` first, then escalate to fuzzy / prefix / OR operators only if the first pass is empty or ambiguous.
+Optional indexing note: \`"searchable": { "phonetic": true }\` keeps the field searchable and enables FalkorDB phonetic matching for the class-wide search index. Query syntax does not change; agents should keep using normal \`search\` strings.
+Without an explicit sort, indexed \`search\` results are returned in FalkorDB relevance order. If you pass a sort, that explicit sort takes precedence.
+
 Supported field metamodel keys:
 
 ${fieldMetamodelTable}
@@ -18522,9 +18700,24 @@ var Session = class {
    * Get domain documentation for LLMs. Returns types (preferred) or fallback.
    */
   async getDomainDocumentation() {
-    const types = await this.getDomainTypes();
-    if (types && (types.includes("export declare class") || types.includes("export async function"))) {
-      return types;
+    const [types, docs] = await Promise.all([
+      this.getDomainTypes(),
+      this.getDomainDocs()
+    ]);
+    const normalizedTypes = types.trim();
+    const normalizedDocs = docs.trim();
+    if (normalizedTypes && (normalizedTypes.includes("export declare class") || normalizedTypes.includes("export async function"))) {
+      if (!normalizedDocs) {
+        return normalizedTypes;
+      }
+      return [
+        normalizedTypes,
+        "Generated usage notes from ./sandbox-tools docs:",
+        normalizedDocs
+      ].join("\n\n");
+    }
+    if (normalizedDocs) {
+      return normalizedDocs;
     }
     const summary = await this.getDomain();
     return this.generateFallbackDocs(summary);

package/dist/{client-Zoo8YITZ.d.mts → client-CigjaeO8.d.mts}

@@ -9,7 +9,7 @@ import { Doc } from '@automerge/automerge/slim';
  * Configuration for the Granular client
  */
 type AccessTokenProvider = () => Promise<string | null | undefined> | string | null | undefined;
-type EndpointMode = 'auto' | 'local' | 'production';
+type EndpointMode = "auto" | "local" | "production";
 interface GranularOptions {
     /** Your Granular API key (for service/CLI auth; use with GRANULAR_API_KEY) */
     apiKey?: string;
@@ -131,7 +131,7 @@ interface ConversationSessionInfo {
     environmentId: string;
     versionId?: string | null;
     docId: string;
-    status: 'active' | 'closed' | 'expired';
+    status: "active" | "closed" | "expired";
     createdAt: string;
     lastSeenAt: string;
     summary?: string | null;
@@ -239,7 +239,7 @@ interface AssignmentListResponse {
  * pin themselves to one immutable ontology version.
  */
 interface BuildPolicy {
-    mode: 'tag' | 'current' | 'pinned';
+    mode: "tag" | "current" | "pinned";
     buildId?: string;
     versionId?: string;
     tagId?: string;
@@ -250,7 +250,7 @@ interface VersionTag {
     tagId: string;
     sandboxId: string;
     name: string;
-    kind: 'channel' | 'release' | 'system';
+    kind: "channel" | "release" | "system";
     targetBuildId?: string | null;
     targetVersionId?: string | null;
     description?: string | null;
@@ -275,7 +275,7 @@ interface EnvironmentData {
     tag?: VersionTag | null;
     tracking?: BuildPolicy;
     buildPolicy: BuildPolicy;
-    updateState?: 'up_to_date' | 'update_available' | 'upgrading' | 'failed';
+    updateState?: "up_to_date" | "update_available" | "upgrading" | "failed";
     createdAt: number;
     updatedAt: number;
 }
@@ -324,7 +324,7 @@ interface Manifest {
 interface ManifestListResponse {
     items: Manifest[];
 }
-type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
+type BuildStatus = "queued" | "building" | "completed" | "failed" | "canceled";
 /**
  * An immutable ontology version derived from a specific manifest revision.
  *
@@ -359,8 +359,8 @@ interface BuildListResponse {
 }
 interface SemanticVersionDiffEntry {
     operationId: string;
-    kind: 'create' | 'update' | 'relationship' | 'effect' | 'eventStream' | 'unknown';
-    changeType: 'added' | 'removed' | 'changed';
+    kind: "create" | "update" | "relationship" | "effect" | "eventStream" | "unknown";
+    changeType: "added" | "removed" | "changed";
     label: string;
     additive: boolean;
     breaking: boolean;
@@ -422,7 +422,7 @@ interface ResolvedEffectBehaviors {
     reverse?: ResolvedEffectReverse;
     approvalRequired?: ResolvedEffectApprovalRequired;
 }
-type EffectInvocationMode = 'execute' | 'dryRun' | 'reverse';
+type EffectInvocationMode = "execute" | "dryRun" | "reverse";
 interface EffectInvocationMetadata {
     mode?: EffectInvocationMode;
     reverseHandler?: string;
@@ -479,9 +479,9 @@ interface ToolSchema {
      * ```
      */
     outputSchema?: Record<string, unknown>;
-    stability?: 'stable' | 'experimental' | 'deprecated';
+    stability?: "stable" | "experimental" | "deprecated";
     provenance?: {
-        source: 'mcp' | 'custom';
+        source: "mcp" | "custom";
     };
     tags?: string[];
     /**
@@ -588,8 +588,8 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 }
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
-type JobStatus = 'queued' | 'running' | 'awaitingTool' | 'awaitingHuman' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
-type JobFeedbackSentiment = 'good' | 'bad';
+type JobStatus = "queued" | "running" | "awaitingTool" | "awaitingHuman" | "succeeded" | "failed" | "timeout" | "canceled";
+type JobFeedbackSentiment = "good" | "bad";
 interface JobFeedbackToolCall {
     callId?: string;
     toolName?: string;
@@ -601,7 +601,7 @@ interface JobFeedbackToolCall {
     durationMs?: number | null;
 }
 interface JobFeedbackMetadata {
-    source: 'sdk';
+    source: "sdk";
     status: JobStatus;
     code: string;
     domainRevision?: string;
@@ -657,7 +657,7 @@ interface Job {
 }
 interface Prompt {
     id: string;
-    type: 'confirm' | 'choice' | 'input';
+    type: "confirm" | "choice" | "input";
     title: string;
     message: string;
     options?: Array<string | {
@@ -676,7 +676,7 @@ interface ConversationMessageShowRefs {
     variableNames?: string[];
 }
 interface ConversationMessageInput {
-    role: 'user' | 'assistant';
+    role: "user" | "assistant";
     content?: string;
     show?: ConversationMessageShowRefs;
     jobId?: string;
@@ -692,7 +692,7 @@ interface ConversationAppendResult {
 }
 interface SessionTranscriptEntry {
     id: string;
-    role: 'user' | 'assistant';
+    role: "user" | "assistant";
     content: string;
     timestamp: number;
     jobId?: string;
@@ -703,9 +703,9 @@ interface SessionTranscriptEntry {
     error?: string;
     show?: ConversationMessageShowRefs;
     historyContent?: string;
-    source: 'conversation' | 'job_code' | 'job_result' | 'job_prompt' | 'job_agent_message';
+    source: "conversation" | "job_code" | "job_result" | "job_prompt" | "job_agent_message";
 }
-type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
+type SessionHeapFieldType = "string" | "number" | "boolean" | "null" | "unknown";
 interface SessionHeapFieldValue {
     name: string;
     type: SessionHeapFieldType;
@@ -733,7 +733,7 @@ interface SessionHeapList {
 }
 interface SessionHeapVariable {
     name: string;
-    kind: 'entry' | 'list' | 'scalar';
+    kind: "entry" | "list" | "scalar";
     entryPath?: string;
     listName?: string;
     value?: string | number | boolean | null;
@@ -770,13 +770,13 @@ interface WSClientOptions {
     onReconnectError?: (info: WSReconnectErrorInfo) => void;
 }
 interface RPCRequest {
-    type: 'rpc';
+    type: "rpc";
     method: string;
     params: unknown;
     id: string;
 }
 interface RPCResponse {
-    type: 'rpc_result' | 'rpc_error';
+    type: "rpc_result" | "rpc_error";
     id: string;
     result?: unknown;
     error?: {
@@ -786,12 +786,12 @@ interface RPCResponse {
     };
 }
 interface SyncMessage {
-    type: 'sync';
+    type: "sync";
     message?: string | number[] | Uint8Array;
     data?: number[];
 }
 interface RPCRequestFromServer {
-    type: 'rpc';
+    type: "rpc";
     method: string;
     params: unknown;
     id: string;
@@ -835,7 +835,7 @@ interface RelationshipInfo {
     /** The foreign model type */
     foreign_model: ModelRef;
     /** Computed relationship kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" */
-    relationship_kind: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
+    relationship_kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many";
 }
 /**
  * Options for defining a relationship between two model types
@@ -934,8 +934,8 @@ interface RecordObjectsOptions {
      */
     onChunkComplete?: (info: RecordObjectsChunkInfo) => void | Promise<void>;
 }
-type RecordImportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
-type RecordImportItemStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
+type RecordImportStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
+type RecordImportItemStatus = "queued" | "processing" | "completed" | "failed" | "canceled";
 interface RecordImportStats {
     totalRecords: number;
     queuedRecords: number;
@@ -1000,10 +1000,14 @@ interface ManifestPropertySpec {
     required?: boolean;
     note?: string | string[];
     enum?: string[] | ManifestEnumRuleSpec;
+    searchable?: boolean | {
+        enabled?: boolean;
+        phonetic?: boolean;
+    };
     filterBy?: boolean | string[] | ManifestFilterBySpec;
     validate?: ManifestValidationRuleSpec[];
 }
-type ManifestValidationOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'true' | 'false' | 'regex' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with';
+type ManifestValidationOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "true" | "false" | "regex" | "contains" | "not_contains" | "starts_with" | "ends_with";
 interface ManifestEnumRuleSpec {
     values: string[];
     message?: string;
@@ -1092,7 +1096,7 @@ interface ManifestEffectDeclaration {
     isStatic?: boolean;
     inputSchema: ManifestEffectSchema;
     outputSchema?: ManifestEffectSchema;
-    stability?: 'stable' | 'experimental' | 'deprecated';
+    stability?: "stable" | "experimental" | "deprecated";
     tags?: string[];
     metamodels?: ManifestEffectMetamodelSpec;
 }
@@ -1153,7 +1157,7 @@ interface ManifestImport {
 }
 interface ManifestVolume {
     name: string;
-    scope: 'sandbox' | 'build' | 'user';
+    scope: "sandbox" | "build" | "user";
     imports?: ManifestImport[];
     operations: ManifestOperation[];
 }
@@ -1196,7 +1200,7 @@ interface StreamEvent {
     environmentId: string;
     sessionId?: string;
     subjectId?: string;
-    source: 'sandbox' | 'api';
+    source: "sandbox" | "api";
     isAcked: boolean;
     createdAt: number;
 }