@secondlayer/subgraphs 3.19.10 → 3.21.0

package/dist/src/index.d.ts

@@ -165,18 +165,45 @@ interface ContractDeployFilter {
 	deployer?: string;
 	contractName?: string;
 }
+/**
+* One declared field of a print payload.
+*
+* A bare {@link ColumnType} is a required scalar (`amount: "uint"`). The
+* composite forms exist because real print payloads are not flat: BNS-V2
+* emits `name` as a NESTED tuple, and a `prints` vocabulary that could only
+* say `"jsonb"` is why a handler reading flat `data.name` type-checked,
+* deployed, and then decoded to null on every event.
+*
+* - `{ type: F, optional: true }` — the KEY becomes optional on `event.data`
+*   (mirrors `always_present: false` in the inferred schema).
+* - `{ tuple: { … } }` — a nested tuple, typed all the way down.
+* - `{ list: F }` — a list of `F`.
+*/
+type PrintField = ColumnType | {
+	type: PrintField
+	optional: true
+} | {
+	tuple: Record<string, PrintField>
+} | {
+	list: PrintField
+};
 interface PrintEventFilter extends TraitScope {
 	type: "print_event";
 	contractId?: string;
 	topic?: string;
 	/**
-	* Optional per-topic field schema. When declared, the handler's `event` is
-	* a discriminated union keyed by `topic` and `event.data` is typed per topic
+	* Per-topic field schema. When declared, the handler's `event` is a
+	* discriminated union keyed by `topic` and `event.data` is typed per topic
 	* (e.g. `{ "completed-deposit": { amount: "uint", sender: "principal" } }`).
-	* Uses the same `ColumnType` vocab as `schema`; nested fields use `"jsonb"`.
-	* Type-level only — not validated at runtime.
+	* Nested tuples, lists, and optional fields are expressible — see
+	* {@link PrintField}.
+	*
+	* Declaring `prints` also opts the source into RUNTIME validation: an
+	* event whose decoded payload does not match is skipped and logged rather
+	* than written as nulls (and the deploy-time field lint is promoted from
+	* a warning to an error).
 	*/
-	prints?: Record<string, Record<string, ColumnType>>;
+	prints?: Record<string, Record<string, PrintField>>;
 }
 /** All subgraph filter types — discriminated on `type` */
 type SubgraphFilter = StxTransferFilter | StxMintFilter | StxBurnFilter | StxLockFilter | FtTransferFilter | FtMintFilter | FtBurnFilter | NftTransferFilter | NftMintFilter | NftBurnFilter | ContractCallFilter | ContractDeployFilter | PrintEventFilter;
@@ -411,7 +438,16 @@ type AggregateResult<
 	max: Record<ColsOf<A, "max">, string | null>
 } : unknown);
 interface SubgraphTableClient<TRow> {
-	findMany(options?: FindManyOptions<TRow>): Promise<TRow[]>;
+	/**
+	* List rows. `fields` narrows BOTH the wire payload and the return type:
+	* the server projects the SELECT to exactly those columns, so an
+	* unrequested field is physically absent — reading it is a compile error,
+	* not `undefined`. The `const` type parameter keeps the literal field
+	* names without `as const` at the call site (same pattern as `aggregate`).
+	*/
+	findMany<const F extends readonly (keyof TRow & string)[] = readonly (keyof TRow & string)[]>(options?: Omit<FindManyOptions<TRow>, "fields"> & {
+		fields?: F
+	}): Promise<Pick<TRow, F[number]>[]>;
 	count(where?: WhereInput<TRow> & SystemWhereAliases): Promise<number>;
 	/**
 	* Scalar aggregates over the filtered set. SUM/MIN/MAX accept numeric columns
@@ -595,13 +631,34 @@ type ContractCallPayload<F> = F extends {
 * per topic; otherwise it falls back to the untyped {@link PrintEventPayload}.
 */
 type PrintEventFor<F> = F extends {
-	prints: infer P extends Record<string, Record<string, ColumnType>>
+	prints: infer P extends Record<string, Record<string, PrintField>>
 } ? { [K in keyof P] : {
 	contractId: string
 	topic: K
-	data: { [Field in keyof P[K]] : ColumnToTS<P[K][Field]> }
+	data: PrintDataOf<P[K]>
 	tx: TxMeta
 } }[keyof P] : PrintEventPayload;
+/** TS type of one declared print field (nested tuples and lists included). */
+type PrintFieldToTS<F> = F extends ColumnType ? ColumnToTS<F> : F extends {
+	type: infer Inner
+	optional: true
+} ? PrintFieldToTS<Inner> : F extends {
+	tuple: infer T extends Record<string, PrintField>
+} ? PrintDataOf<T> : F extends {
+	list: infer Item
+} ? PrintFieldToTS<Item>[] : unknown;
+type OptionalFieldKeys<T> = { [K in keyof T] : T[K] extends {
+	optional: true
+} ? K : never }[keyof T];
+/** Collapse an intersection into one object literal, so hovering `event.data`
+*  shows the fields rather than `A & B`. */
+type Flatten<T> = { [K in keyof T] : T[K] } & {};
+/**
+* `event.data` for one topic: declared fields typed, with
+* `{ optional: true }` fields made optional KEYS (a field observed on only
+* some events must not be typed as always present).
+*/
+type PrintDataOf<T extends Record<string, PrintField>> = Flatten<{ [K in Exclude<keyof T, OptionalFieldKeys<T>>] : PrintFieldToTS<T[K]> } & { [K in OptionalFieldKeys<T>]? : PrintFieldToTS<T[K]> }>;
 /** The event payload a handler receives for a given source filter. */
 type EventForFilter<F extends SubgraphFilter> = F extends {
 	type: "print_event"
@@ -680,6 +737,18 @@ declare function defineSubgraph<
 	const Sources extends Record<string, SubgraphFilter>,
 	const S extends SubgraphSchema
 >(def: TypedSubgraphDefinition<Sources, S>): TypedSubgraphDefinition<Sources, S>;
+type PrintValidationResult = {
+	ok: true
+} | {
+	ok: false
+	reason: string
+};
+/**
+* Validate one decoded print event against a source's `prints` declaration.
+* Returns `{ ok: true }` when no declaration covers this topic (undeclared
+* topics are not the developer's stated contract, so they pass through).
+*/
+declare function validatePrintPayload(prints: Record<string, Record<string, PrintField>> | undefined, topic: string, data: Record<string, unknown>): PrintValidationResult;
 /**
 * Empirical print-payload schema inference. Callers (the index print-schema
 * endpoint) extract topic + raw Clarity hex per row; this module deserializes
@@ -793,19 +862,41 @@ interface TableDiff {
 	removedTables: string[];
 	/** Per-table column diffs (only for tables present in both) */
 	tables: Record<string, ColumnDiff>;
+	/** Per-table uniqueKeys / composite-index diffs (tables present in both) */
+	constraints: Record<string, ConstraintDiff>;
 }
 interface ColumnDiff {
 	added: string[];
 	removed: string[];
+	/** Data-shape changes (type/nullable/default) — breaking. */
 	changed: string[];
+	/** Only the `indexed`/`search` flags differ — index DDL, never a rebuild. */
+	indexChanged: string[];
+}
+interface ConstraintDiff {
+	/** New uniqueKeys entries → `ALTER TABLE … ADD CONSTRAINT` (additive). */
+	addedUniqueKeys: string[][];
+	/** Removed uniqueKeys entries — breaking: handler upserts may target them. */
+	removedUniqueKeys: string[][];
+	/** New composite `indexes` entries → CREATE INDEX (additive). */
+	addedIndexes: string[][];
+	/** Removed composite `indexes` entries → DROP INDEX (additive). */
+	removedIndexes: string[][];
 }
 /**
 * Compare two multi-table subgraph schemas and return differences.
+*
+* Index-only changes (`indexed`/`search` flags, composite `indexes`) are
+* reported separately from data-shape changes: an index never requires a
+* rebuild, so it must never land in `changed`/breaking — flipping
+* `indexed: true` on a populated column used to cost a full reindex.
 */
 declare function diffSchema(existing: SubgraphSchema, incoming: SubgraphSchema): TableDiff;
 /**
 * Returns true if the diff contains any breaking changes
-* (removed tables, removed columns, or changed column types).
+* (removed tables, removed columns, changed column types, or removed
+* uniqueKeys — handler upserts `ON CONFLICT` against those).
+* Index-flag and composite-index changes are never breaking.
 */
 declare function hasBreakingChanges(diff: TableDiff): {
 	breaking: boolean
@@ -816,6 +907,10 @@ interface DeployDiff {
 	removedTables: string[];
 	addedColumns: Record<string, string[]>;
 	breakingChanges: string[];
+	/** Columns whose only change was the `indexed`/`search` flag (index DDL applied in place). */
+	indexChanges?: Record<string, string[]>;
+	/** uniqueKeys added in place via ALTER TABLE … ADD CONSTRAINT. */
+	addedUniqueKeys?: Record<string, string[][]>;
 }
 interface ByoMigrationPlan {
 	schemaName: string;
@@ -877,6 +972,8 @@ declare function deploySchema(db: AnyDb, def: SubgraphDefinition, handlerPath: s
 	subgraphId: string
 	version: string
 	diff?: DeployDiff
+	/** Non-fatal caveats the caller should surface (e.g. handler grafts at tip). */
+	warnings?: string[]
 }>;
 /** A (decoded event type, optional contract scope) pair the sparse probe
 *  checks. Contract scoping is what makes token-subgraph reindexes leap over
@@ -891,4 +988,4 @@ type SparseProbeTarget = {
 declare function canSparseScan(subgraph: SubgraphDefinition): boolean;
 /** Probe targets for a subgraph's filters: decoded type + contract scope when\\n*  the filter pins one (assetIdentifier "SP….contract::asset" or contractId). */
 declare function sparseProbeTargets(subgraph: SubgraphDefinition): SparseProbeTarget[];
-export { validateSubgraphDefinition, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, diffSchema, deploySchema, defineSubgraph, canSparseScan, camelizeDataKey, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintSample, PrintEventPayload, PrintEventFor, PrintEventFilter, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferredTopicSchema, InferredPrintField, InferTableRow, InferSubgraphClient, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, EventForFilter, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ByoMigrationPlan, ByoBreakingChangeError, AnyEvent, AggregateSpec, AggregateResult };
+export { validateSubgraphDefinition, validatePrintPayload, sparseProbeTargets, resumeReindex, renderDeployPlan, reindexSubgraph, pgSchemaName, inferPrintTopics, hasBreakingChanges, generateSubgraphSQL, generatePrismaSchema, generateKyselySchema, generateIndexSchema, generateDrizzleSchema, diffSchema, deploySchema, defineSubgraph, canSparseScan, camelizeDataKey, backfillSubgraph, WriteRow, WhereInput, TypedSubgraphDefinition, TypedSubgraphContext, TypedHandlers, TxMeta, TableDiff, SystemRow, SubscribeOptions, SubgraphTableClient, SubgraphTable, SubgraphSchema, SubgraphHandler, SubgraphFilter, SubgraphDefinition, SubgraphContext, SubgraphColumn, StxTransferPayload, StxTransferFilter, StxMintPayload, StxMintFilter, StxLockPayload, StxLockFilter, StxBurnPayload, StxBurnFilter, SparseProbeTarget, RowValue, ReindexOptions, PrismaGenOptions, PrintValidationResult, PrintSample, PrintFieldToTS, PrintField, PrintEventPayload, PrintEventFor, PrintEventFilter, PrintDataOf, NftTransferPayload, NftTransferFilter, NftMintPayload, NftMintFilter, NftBurnPayload, NftBurnFilter, KyselyGenOptions, InferredTopicSchema, InferredPrintField, InferTableRow, InferSubgraphClient, InferColumnType, IndexCodegenTarget, IndexCodegenOptions, INDEX_CODEGEN_TABLES, GeneratedSQL, FtTransferPayload, FtTransferFilter, FtMintPayload, FtMintFilter, FtBurnPayload, FtBurnFilter, FindManyOptions, EventForFilter, DrizzleGenOptions, DeployPlan, DeployDiff, ContractDeployPayload, ContractDeployFilter, ContractCallPayload, ContractCallFilter, ContractCallEvent, ComputedValue, ComparisonFilter, ColumnType, ColumnToTS, ColumnDiff, ByoMigrationPlan, ByoBreakingChangeError, AnyEvent, AggregateSpec, AggregateResult };

package/dist/src/index.js

@@ -14,6 +14,44 @@ var ColumnTypeSchema = z.enum([
   "timestamp",
   "jsonb"
 ]);
+var PrintFieldSchema = z.lazy(() => z.union([
+  ColumnTypeSchema,
+  z.object({ type: PrintFieldSchema, optional: z.literal(true) }),
+  z.object({ tuple: z.record(z.string(), PrintFieldSchema) }),
+  z.object({ list: PrintFieldSchema })
+]));
+var AbiTypeSchema = z.lazy(() => z.union([
+  z.string(),
+  z.object({ buff: z.object({ length: z.number() }) }),
+  z.object({ "string-ascii": z.object({ length: z.number() }) }),
+  z.object({ "string-utf8": z.object({ length: z.number() }) }),
+  z.object({ optional: AbiTypeSchema }),
+  z.object({
+    list: z.object({ type: AbiTypeSchema, length: z.number() })
+  }),
+  z.object({
+    tuple: z.array(z.object({ name: z.string(), type: AbiTypeSchema }))
+  }),
+  z.object({
+    response: z.object({ ok: AbiTypeSchema, error: AbiTypeSchema })
+  })
+]));
+var AbiContractSchema = z.object({
+  functions: z.array(z.object({
+    name: z.string(),
+    access: z.enum(["public", "read-only", "private"], {
+      message: "ABI access must be public | read-only | private — a raw Hiro/Clarinet ABI uses `read_only`. Normalize it first: normalizeAbi() from @secondlayer/stacks/clarity."
+    }),
+    args: z.array(z.object({ name: z.string(), type: AbiTypeSchema })),
+    outputs: AbiTypeSchema
+  })),
+  maps: z.array(z.unknown()).optional(),
+  variables: z.array(z.unknown()).optional(),
+  fungible_tokens: z.array(z.unknown()).optional(),
+  non_fungible_tokens: z.array(z.unknown()).optional(),
+  implemented_traits: z.array(z.unknown()).optional(),
+  defined_traits: z.array(z.unknown()).optional()
+});
 var SubgraphColumnSchema = z.object({
   type: ColumnTypeSchema,
   nullable: z.boolean().optional(),
@@ -62,9 +100,9 @@ var SubgraphFilterSchema = z.object({
   contractName: z.string().optional(),
   topic: z.string().optional(),
   lockedAddress: z.string().optional(),
-  abi: z.record(z.string(), z.any()).optional(),
+  abi: AbiContractSchema.optional(),
   trait: z.string().optional(),
-  prints: z.record(z.string(), z.record(z.string(), ColumnTypeSchema)).optional()
+  prints: z.record(z.string(), z.record(z.string(), PrintFieldSchema)).optional()
 }).strict();
 var SubgraphDefinitionSchema = z.object({
   name: SubgraphNameSchema,
@@ -837,6 +875,87 @@ import {
   deserializeCV as deserializeCV2,
   toCamelCase
 } from "@secondlayer/stacks/clarity";
+
+// src/runtime/print-validate.ts
+var COLUMN_TYPES = new Set([
+  "text",
+  "uint",
+  "int",
+  "principal",
+  "boolean",
+  "timestamp",
+  "jsonb"
+]);
+function isColumnType(field) {
+  return typeof field === "string" && COLUMN_TYPES.has(field);
+}
+function matchesField(field, value) {
+  if (isColumnType(field)) {
+    switch (field) {
+      case "uint":
+      case "int":
+        return typeof value === "bigint" || typeof value === "number";
+      case "boolean":
+        return typeof value === "boolean";
+      case "text":
+      case "principal":
+      case "timestamp":
+        return typeof value === "string" || typeof value === "number" || typeof value === "bigint";
+      case "jsonb":
+        return value !== undefined;
+    }
+  }
+  if (typeof field !== "object" || field === null)
+    return false;
+  if ("optional" in field) {
+    return value === undefined || value === null || matchesField(field.type, value);
+  }
+  if ("tuple" in field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return false;
+    }
+    return matchesTopic(field.tuple, value).ok;
+  }
+  if ("list" in field) {
+    return Array.isArray(value) && value.every((item) => matchesField(field.list, item));
+  }
+  return false;
+}
+function matchesTopic(declared, data) {
+  for (const [name, field] of Object.entries(declared)) {
+    const present = name in data;
+    const optional = typeof field === "object" && field !== null && "optional" in field;
+    if (!present) {
+      if (optional)
+        continue;
+      return { ok: false, reason: `missing declared field "${name}"` };
+    }
+    if (!matchesField(field, data[name])) {
+      return {
+        ok: false,
+        reason: `field "${name}" does not match its declared type (got ${describe(data[name])})`
+      };
+    }
+  }
+  return { ok: true };
+}
+function describe(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+}
+function validatePrintPayload(prints, topic, data) {
+  if (!prints)
+    return { ok: true };
+  const declared = prints[topic];
+  if (!declared)
+    return { ok: true };
+  return matchesTopic(declared, data);
+}
+
+// src/runtime/runner.ts
 var DEFAULT_ERROR_THRESHOLD = 50;
 function camelCase(str) {
   return str.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
@@ -1081,6 +1200,7 @@ function buildEventPayload(filter, tx, event) {
 async function runHandlers(subgraph, matched, ctx, opts) {
   let processed = 0;
   let errors = 0;
+  let skipped = 0;
   const threshold = opts?.errorThreshold ?? DEFAULT_ERROR_THRESHOLD;
   const filterLookup = new Map;
   if (!Array.isArray(subgraph.sources)) {
@@ -1105,7 +1225,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
         errors,
         threshold
       });
-      return { processed, errors };
+      return { processed, errors, ...skipped > 0 ? { skipped } : {} };
     }
     const handler = subgraph.handlers[sourceName] ?? subgraph.handlers["*"] ?? null;
     if (!handler) {
@@ -1161,6 +1281,21 @@ async function runHandlers(subgraph, matched, ctx, opts) {
       if (event !== null && filter?.type === "print_event" && filter.topic && payload.topic !== filter.topic) {
         continue;
       }
+      if (event !== null && filter?.type === "print_event" && filter.prints) {
+        const printPayload = payload;
+        const verdict = validatePrintPayload(filter.prints, printPayload.topic ?? "", printPayload.data ?? {});
+        if (!verdict.ok) {
+          skipped++;
+          logger2.warn("Print payload does not match declared prints schema", {
+            subgraph: subgraph.name,
+            sourceName,
+            topic: printPayload.topic,
+            txId: tx.tx_id,
+            reason: verdict.reason
+          });
+          continue;
+        }
+      }
       await handler(payload, ctx);
       processed++;
     } catch (err) {
@@ -1175,7 +1310,7 @@ async function runHandlers(subgraph, matched, ctx, opts) {
       });
     }
   }
-  return { processed, errors };
+  return { processed, errors, ...skipped > 0 ? { skipped } : {} };
 }
 
 // src/runtime/source-matcher.ts
@@ -3843,31 +3978,53 @@ import { sql as sql4 } from "kysely";
 function toJsonSafe(obj) {
   return JSON.parse(JSON.stringify(obj, (_key, value) => typeof value === "bigint" ? value.toString() : value));
 }
+function columnDataShape(col) {
+  const { indexed, search, ...rest } = col ?? {};
+  return JSON.stringify(rest, Object.keys(rest).sort());
+}
+function diffKeyLists(existing, incoming) {
+  const key2 = (cols) => JSON.stringify(cols);
+  const existingSet = new Set((existing ?? []).map(key2));
+  const incomingSet = new Set((incoming ?? []).map(key2));
+  return {
+    added: (incoming ?? []).filter((cols) => !existingSet.has(key2(cols))),
+    removed: (existing ?? []).filter((cols) => !incomingSet.has(key2(cols)))
+  };
+}
 function diffSchema(existing, incoming) {
   const existingTables = new Set(Object.keys(existing));
   const incomingTables = new Set(Object.keys(incoming));
   const addedTables = [...incomingTables].filter((t) => !existingTables.has(t));
   const removedTables = [...existingTables].filter((t) => !incomingTables.has(t));
   const tables = {};
+  const constraints = {};
   for (const tableName of incomingTables) {
     if (!existingTables.has(tableName))
       continue;
-    const existingCols = existing[tableName]?.columns;
-    const incomingCols = incoming[tableName]?.columns;
+    const existingTable = existing[tableName];
+    const incomingTable = incoming[tableName];
+    const existingCols = existingTable?.columns;
+    const incomingCols = incomingTable?.columns;
     const existingKeys = new Set(Object.keys(existingCols));
     const incomingKeys = new Set(Object.keys(incomingCols));
+    const common = [...incomingKeys].filter((k) => existingKeys.has(k));
+    const sortedStringify = (o) => JSON.stringify(o, Object.keys(o).sort());
     tables[tableName] = {
       added: [...incomingKeys].filter((k) => !existingKeys.has(k)),
       removed: [...existingKeys].filter((k) => !incomingKeys.has(k)),
-      changed: [...incomingKeys].filter((k) => {
-        if (!existingKeys.has(k))
-          return false;
-        const sortedStringify = (o) => JSON.stringify(o, Object.keys(o).sort());
-        return sortedStringify(existingCols[k]) !== sortedStringify(incomingCols[k]);
-      })
+      changed: common.filter((k) => columnDataShape(existingCols[k]) !== columnDataShape(incomingCols[k])),
+      indexChanged: common.filter((k) => columnDataShape(existingCols[k]) === columnDataShape(incomingCols[k]) && sortedStringify(existingCols[k]) !== sortedStringify(incomingCols[k]))
+    };
+    const uq = diffKeyLists(existingTable?.uniqueKeys, incomingTable?.uniqueKeys);
+    const ix = diffKeyLists(existingTable?.indexes, incomingTable?.indexes);
+    constraints[tableName] = {
+      addedUniqueKeys: uq.added,
+      removedUniqueKeys: uq.removed,
+      addedIndexes: ix.added,
+      removedIndexes: ix.removed
     };
   }
-  return { addedTables, removedTables, tables };
+  return { addedTables, removedTables, tables, constraints };
 }
 function hasBreakingChanges(diff) {
   const reasons = [];
@@ -3882,6 +4039,11 @@ function hasBreakingChanges(diff) {
       reasons.push(`${table}: changed columns [${colDiff.changed.join(", ")}]`);
     }
   }
+  for (const [table, conDiff] of Object.entries(diff.constraints ?? {})) {
+    if (conDiff.removedUniqueKeys.length > 0) {
+      reasons.push(`${table}: removed uniqueKeys [${conDiff.removedUniqueKeys.map((cols) => `(${cols.join(", ")})`).join(", ")}]`);
+    }
+  }
   return { breaking: reasons.length > 0, reasons };
 }
 function bumpPatch(version) {
@@ -3987,7 +4149,12 @@ async function deploySchema(db, def, handlerPath, opts) {
       return {
         action: handlerChanged ? "handler_updated" : "unchanged",
         subgraphId: existing.id,
-        version: existing.version
+        version: existing.version,
+        ...handlerChanged ? {
+          warnings: [
+            "handler changed but schema did not: new logic applies from the current tip only. Rows already indexed were computed by the previous handler. To recompute history, redeploy with --reindex (or backfill a range)."
+          ]
+        } : {}
       };
     }
     if (existing.schema_hash === hash && opts?.forceReindex) {
@@ -4058,6 +4225,65 @@ async function deploySchema(db, def, handlerPath, opts) {
           }
         }
       }
+      const existingSchema = existing.definition.schema;
+      const flagFlips = {};
+      const needsTrgmForFlips = Object.entries(diff.tables).some(([tableName, colDiff]) => colDiff.indexChanged.some((colName) => def.schema[tableName]?.columns[colName]?.search && !existingSchema[tableName]?.columns[colName]?.search));
+      if (needsTrgmForFlips) {
+        await sql4.raw("CREATE EXTENSION IF NOT EXISTS pg_trgm").execute(ddlDb);
+      }
+      for (const [tableName, colDiff] of Object.entries(diff.tables)) {
+        if (colDiff.indexChanged.length === 0)
+          continue;
+        flagFlips[tableName] = colDiff.indexChanged;
+        const qualifiedName = `${schemaName}.${tableName}`;
+        for (const colName of colDiff.indexChanged) {
+          const was = existingSchema[tableName]?.columns[colName];
+          const now = def.schema[tableName]?.columns[colName];
+          if (!now)
+            continue;
+          const plainIdx = `idx_${schemaName}_${tableName}_${colName}`;
+          const trgmIdx = `idx_${schemaName}_${tableName}_${colName}_trgm`;
+          if (now.indexed && !was?.indexed) {
+            await sql4.raw(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${plainIdx} ON ${qualifiedName} (${colName})`).execute(ddlDb);
+          } else if (!now.indexed && was?.indexed) {
+            await sql4.raw(`DROP INDEX CONCURRENTLY IF EXISTS ${schemaName}.${plainIdx}`).execute(ddlDb);
+          }
+          if (now.search && !was?.search) {
+            await sql4.raw(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${trgmIdx} ON ${qualifiedName} USING gin (${colName} gin_trgm_ops)`).execute(ddlDb);
+          } else if (!now.search && was?.search) {
+            await sql4.raw(`DROP INDEX CONCURRENTLY IF EXISTS ${schemaName}.${trgmIdx}`).execute(ddlDb);
+          }
+        }
+      }
+      const addedUq = {};
+      for (const [tableName, conDiff] of Object.entries(diff.constraints)) {
+        const qualifiedName = `${schemaName}.${tableName}`;
+        for (const cols of conDiff.addedUniqueKeys) {
+          const constraintName = `uq_${schemaName}_${tableName}_${cols.join("_")}`;
+          const exists = await sql4`
+						SELECT EXISTS (
+							SELECT 1 FROM pg_constraint
+							WHERE conname = ${constraintName}
+						) AS "exists"
+					`.execute(ddlDb).then((r) => r.rows[0]?.exists ?? false);
+          if (!exists) {
+            await sql4.raw(`ALTER TABLE ${qualifiedName} ADD CONSTRAINT ${constraintName} UNIQUE (${cols.join(", ")})`).execute(ddlDb);
+          }
+          addedUq[tableName] = [...addedUq[tableName] ?? [], cols];
+        }
+        for (const cols of conDiff.addedIndexes) {
+          const i = (def.schema[tableName]?.indexes ?? []).findIndex((entry) => JSON.stringify(entry) === JSON.stringify(cols));
+          const idxName = `idx_${schemaName}_${tableName}_composite_${i}`;
+          await sql4.raw(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${idxName} ON ${qualifiedName} (${cols.join(", ")})`).execute(ddlDb);
+        }
+        for (const cols of conDiff.removedIndexes) {
+          const i = (existingSchema[tableName]?.indexes ?? []).findIndex((entry) => JSON.stringify(entry) === JSON.stringify(cols));
+          if (i < 0)
+            continue;
+          const idxName = `idx_${schemaName}_${tableName}_composite_${i}`;
+          await sql4.raw(`DROP INDEX CONCURRENTLY IF EXISTS ${schemaName}.${idxName}`).execute(ddlDb);
+        }
+      }
       const sg2 = await registerSubgraph(db, regData);
       const addedCols = {};
       for (const [t, colDiff] of Object.entries(diff.tables)) {
@@ -4068,7 +4294,9 @@ async function deploySchema(db, def, handlerPath, opts) {
         addedTables: diff.addedTables,
         removedTables: [],
         addedColumns: addedCols,
-        breakingChanges: []
+        breakingChanges: [],
+        ...Object.keys(flagFlips).length > 0 ? { indexChanges: flagFlips } : {},
+        ...Object.keys(addedUq).length > 0 ? { addedUniqueKeys: addedUq } : {}
       };
       return {
         action: "updated",
@@ -4104,6 +4332,7 @@ function getDefault(type) {
 }
 export {
   validateSubgraphDefinition,
+  validatePrintPayload,
   sparseProbeTargets,
   resumeReindex,
   renderDeployPlan,
@@ -4126,5 +4355,5 @@ export {
   ByoBreakingChangeError
 };
 
-//# debugId=9D76C8C8FCA229DB64756E2164756E21
+//# debugId=1014943AF0D5A26B64756E2164756E21
 //# sourceMappingURL=index.js.map