Kits parity issues

[CorieW]

Below are comments for each extension to kit migration. Each comment displays the differences between the extension and the corresponding kit.

Valid differences

• Some changes are due to migrations from gen1 functions to gen2. These specific changes have been excluded from the comments below.
• yes / no params changed to booleans (with defineBoolean) in kits.
• Service account params have been removed in kits, as they conflict with declarative security (requiresRole) stuff.
• LOCATION params have been removed in kits, as kits builds this feature in.
• Some changes may be due to dependency upgrades, or more recent Node versions.
• Extensions previously didn't support a number type, so they used text/string type with regex (e.g. validation: ^[0-9]) for validation. Kits now use defineInt, so they don't require the regex validation.
• required: defaults to true when omitted in extension.yaml, and several extensions omit it on params their own code and descriptions treat as optional (BACKUP_COLLECTION, DEFAULT_REPLY_TO, USERS_COLLECTION, TEMPLATES_COLLECTION). Kits match the code behaviour (optional, empty → undefined), not the yaml.
• defineSecret cannot be optional — SecretParamOptions only takes label/description, so any bound secret must exist at deploy. Extension params declared type: secret, required: false (API_KEY, GOOGLE_AI_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, and the send-email SMTP/OAuth secrets) therefore become mandatory-at-deploy in kits. Platform constraint, not a kit choice.
• Where an extension's yaml default disagreed with its own code fallback (firestore-genai-chatbot / firestore-vector-search COLLECTION_NAME, delete-user-data AUTO_DISCOVERY_SEARCH_FIELDS), kits standardise on the yaml default.
• No firebase-functions/params equivalent of the ${DATABASE_INSTANCE} system param. In the extension, the built-in FIREBASE_CONFIG.databaseURL resolves without prompting. This is something kit has to handle itself. Only applicable in rtdb-limit-child-nodes extension/kit.
• IMG_BUCKET / EXTENSION_BUCKET use the params BUCKET_PICKER (a ResourceInput), which cannot also carry a validationRegex or example, so those two params keep the picker instead of the extensions' regex and example. The picker constrains input to real buckets, which is stronger, and this will stay as is.
• Function resource properties (timeout, memory, maxInstances from each extension's resources[].properties) have not been systematically compared against the kit function definitions, and no sweep is planned — this may be something firebase-tools handles itself when deploying kits.
• Kits have no deploy-time status surface. Extensions reported progress and failures through getExtensions().runtime().setProcessingState(...); nothing equivalent exists for kits, so deploy-time outcomes are only visible in function logs. Affects bigquery-firestore-export (10 call sites), firestore-bigquery-export (lifecycle hooks), firestore-translate-text (backfill) and firestore-vector-search (backfill gating).
• billingRequired: true has no kit equivalent, so kits cannot declare the billing requirement that firestore-translate-text and rtdb-limit-child-nodes declared in their yaml.
• rtdb-limit-child-nodes renamed NODE_PATH to RTDB_NODE_PATH and will keep it: Node.js reserves NODE_PATH for module resolution, so the original name is overwritten at runtime.
• Event payload shapes changed with the gen1 to gen2 migration: { change, context } became { data, params } (firestore-counter, firestore-translate-text), and speech-to-text now publishes { message, stack } where the extension published a non-enumerable Error that serialised to {}. Consumers reading context.params need updating.
• firestore-vector-search publishes Eventarc events where the extension published none (it declared the event types in extension.yaml but never published them). The kit exceeds the extension here rather than falling short.
• extension.yaml used to have a reason for roles and APIs. Now with kits, only requiresAPI accepts a reason param. requiresRole doesn't accept a reason.

Look into

• Potentially could use FIREBASE_KIT_INSTANCE_ID? Answered: yes - firebase-tools >= 15.27.0 injects it for kit instances (discovery, deploy, emulator, serve). It must be read via process.env, never declared as a param (the params machinery only consults .env, and the FIREBASE_ prefix is reserved there). Implemented for delete-user-data in fix(delete-user-data): read the kit instance id from FIREBASE_KIT_INSTANCE_ID #3060; migration of the remaining kits tracked in refactor(kits): migrate all kits from the INSTANCE_ID param to the injected FIREBASE_KIT_INSTANCE_ID #3063.

Remaining parity work

Correctness / production-firing

• bigquery-firestore-export: soft failures → hard failures — cases the extension reported PROCESSING_COMPLETE now throw under retry: true → retry storms (§7a–7c, §8) - fix(bigquery-firestore-export): stop retrying deploy-time misconfigurations #2983 — fix(bigquery-firestore-export): stop retrying deploy-time misconfigurations #2983 @IzaakGough look into this, what should the kit behaviour be — fix(bigquery-firestore-export): stop retrying the two failures the extension treated as terminal #3086 (merged) stops retrying the two terminal failures; config-validation residual tracked in issue fix(bigquery-firestore-export): soft failures throw and retry-storm #3008
• firestore-send-email: SendGrid + AUTH_TYPE=OAuth2 sends fail — secret gating forces apiKey: undefined, setApiKey never called — issue fix(firestore-send-email): SendGrid sends fail with AUTH_TYPE=OAuth2 #3009 — fix(firestore-send-email): keep SMTP_PASSWORD available so SendGrid works with AUTH_TYPE=OAuth2 #3089 (open)
• storage-resize-images: partial-env crashes — issue fix(storage-resize-images): degrade gracefully against a partial env #3138 - fix(storage-resize-images): degrade gracefully against a partial env #3002 (approved, unmerged)
• storage-resize-images: CONTENT_FILTER_LEVEL "Off" option stored the string False instead of OFF, so every resize with the filter off threw at runtime — issue fix(storage-resize-images): the "Off" content-filter selection stores "False" and fails every event #3047 — fix(storage-resize-images): map the Off content-filter option to OFF #3064 (open, Needs Changes; follow-ups fix(storage-resize-images): IS_ANIMATED select label is True, the extension says Yes #3123 label, feat(storage-resize-images): reject unknown IMAGE_TYPE values at config resolve time #3124 stale IMAGE_TYPE validation)
• firestore-send-email: DATABASE_REGION used as function region — the conflation fixed for firestore-bigquery-export by fix(firestore-bigquery-export): stop using DATABASE_REGION as the function region #3066/fix(firestore-bigquery-export): place functions from DATABASE_REGION with a multi-region mapping #3101 is still live here: kits/firestore-send-email/src/config.ts:378 passes params.databaseRegion straight to region, and eur3/nam5/nam7 remain selectable, so deploy hard-fails on a multi-region database — issue fix(firestore-send-email): DATABASE_REGION used as function region breaks multi-region deploys #3069 — fix(firestore-send-email): map DATABASE_REGION to a Cloud Run region for function placement #3102 (open, unmerged)
• Cross-kit: PROJECT_ID resolution — the extension reads process.env.PROJECT_ID (functions/src/config.ts:166), injected by the Extensions runtime, and defaults BIGQUERY_PROJECT_ID to the ${PROJECT_ID} system param; kits use firebase-functions/params projectID (kits/firestore-bigquery-export/src/config.ts:119,627), which resolves from FIREBASE_CONFIG.projectId and yields "" when that is absent. Surfaced by 🐛 [@firebase-function-kits/firestore-bigquery-export] afterFirstDeploy taskqueue initialization failed from missing PROJECT_ID #3120 (and the older 🐛 [firestore-bigquery-export] Project ID resolves to undefined in Gen2 / Cloud Run functions #2778); the shared change-tracker fallback bqProjectId || process.env.PROJECT_ID (firestore-bigquery-change-tracker/src/bigquery/snapshot.ts:68) is fixed in fix(bigquery): preserve project on view updates #3121 (open), which the kit inherits via @firebaseextensions/firestore-bigquery-change-tracker@^2.1.0
• Cross-kit: no kit that publishes events declares roles/eventarc.publisher (firestore-counter, firestore-translate-text, firestore-bigquery-export, speech-to-text); with EVENTARC_CHANNEL set the awaited publish 403s and the function fails before doing any work - issue kits: declare roles/eventarc.publisher so event publishing does not 403 #3125

Migration / consumer breaks

• firestore-vector-search: status field shape change — status.<instanceId>.state consumers break (§6) - issue decision(firestore-vector-search): status field shape, nested per-instance vs flat #3139 (decision; fix(firestore-vector-search): restore terminal-state skip on embedOnWrite #3092 leaves the shape out of scope)
• firestore-vector-search: OpenAI index dimension does not match the vectors written — dimensionFor() returns 512 for openai (kits/firestore-vector-search/src/export-config.ts:105) while ada-002 writes 1536 (src/embeddings/client/text/open_ai.ts:34), so findNearest cannot use the index. Inherited from the extension and reproduced exactly by fix(firestore-vector-search): restore the extension's embedding defaults #3096; decision(firestore-vector-search): embedding model and dimension defaults #3029 decided the model, not the dimension — issue decision(firestore-vector-search): OpenAI vector index is 512 dimensions while the vectors are 1536 #3105. createIndex never compares dimension (src/queries/setup.ts:49-56), so any fix needs a delete-the-old-index migration note
• firestore-bigquery-export: legacy back-compat event types dropped — the extension published both firebase.extensions.firestore-counter.v1.* (legacy) and …firestore-bigquery-export.v1.*; the kit publishes only the new ones — issue fix(firestore-bigquery-export): republish the legacy firestore-counter event types #3108 — fix(firestore-bigquery-export): republish the legacy firestore-counter event types #3111 @cabljac @CorieW
• speech-to-text: transcoded .wav lands in a different Storage location (§1, including the .txt path's retained replace("tmp/", …)) - .txt remnant fixed in fix(speech-to-text): stop stripping tmp/ from the .txt transcription path #3073; the .wav location decision remains open - issue decision(speech-to-text): transcoded .wav lands in a different Storage location #3140
• Cross-kit: event payload shapes — {change, context} → {data, params} (firestore-counter §5, firestore-translate-text), speech-to-text error {} → {message, stack} — decision recorded in issue decision(kits): event payload shape {change, context} vs {data, params} #3027 (open): NOT intentional gen2 design, fix — fix(kits): restore the extensions' event payload shapes #3098 @CorieW

Events gaps

• firestore-translate-text: early-returns on !event.data without emitting start/completion events; the extension always emitted both — issue fix(firestore-translate-text): always emit start and completion events #3020 @cabljac

Behavior divergence (fix or decide)

• firestore-vector-search: re-embed-on-update flipped (the extension never re-embeds terminal docs) + ERROR-retry flipped (§6a/6b) — issue fix(firestore-vector-search): restore re-embed and ERROR-retry semantics #3011 DECISION: parity where possible with extension — fix(firestore-vector-search): restore terminal-state skip on embedOnWrite #3092 @CorieW
• firestore-vector-search: backfill de-batched — per-document tasks and embedding calls, metadata-doc gate lost, collection().get() loads every document into memory → every redeploy re-embeds the whole collection (§9) — DECISION: fix, aim for parity — issue fix(firestore-vector-search): restore batched backfill #3012 — fix(firestore-vector-search): restore batched backfill #3097 @CorieW
• firestore-vector-search: multimodal unimplemented yet still an offered EMBEDDING_PROVIDER value (§3) - fix(firestore-vector-search): remove the unimplemented multimodal provider value #3074 — fix(firestore-vector-search): remove the unimplemented multimodal provider value #3074 — DECISION: fix, aim for parity @CorieW + @cabljac
• firestore-genai-chatbot: startup fail-fast removed (validateRequiredEnvVars()) — DECISION: track as follow-up — issue fix(firestore-genai-chatbot): validate conditional config combinations at first invocation #3022
• Cross-kit: AI-provider location fallback — firestore-genai-chatbot VERTEX_AI_MODEL_LOCATION=null no longer means "function region" (§3); firestore-translate-text vertex region from FUNCTION_REGION/genkit default (§2); firestore-vector-search same class (§5) — knock-on of the LOCATION removal, one decision — issue decision(kits): AI-provider location fallback after the LOCATION removal #3028 - as an example fbe had DATABASE_REGION (or similar) that is removed in the kit now, on kits branch.
  • Related: PR #2943 changes chatbot and translation to use the global Vertex AI endpoint. Partial coverage: vector search is untouched, and decision(kits): AI-provider location fallback after the LOCATION removal #3028’s explicit-region decision is not fully implemented. This task remains open.
• storage-resize-images: programmatic default flips — deleteOriginal unset onSuccess → never; isAnimated unset false → true (§1–2) — DECISION: deleteOriginal parity (onSuccess); isAnimated stays true, the extension's unset-false was a shipped bug (|| undefined), fixed and documented in README — issue fix(storage-resize-images): restore programmatic defaults for deleteOriginal and isAnimated #3024 — fix(storage-resize-images): restore the extension's default for an omitted deleteOriginal #3100
• bigquery-firestore-export: DISPLAY_NAME edits silently no-op — never added to the DTS update mask — issue fix(bigquery-firestore-export): DISPLAY_NAME edits silently no-op on update #3141 - fix(bigquery-firestore-export): apply DISPLAY_NAME changes on update #2980 (open)
• bigquery-firestore-export: BigQuery job/billing project now config.projectId — the extension used the ADC default (§10) — decide/Note @IzaakGough
• bigquery-firestore-export: TRANSFER_CONFIG_NAME enables the extension's dead link-config branch — behavior beyond the extension (§3) — decide/Note fix(bigquery-firestore-export): notify this instance's topic when linking a config #2960
• firestore-translate-text: null input routes differently — typeof null === "object", so the extension sends { input: null } to translateMultiple and throws in Object.entries (functions/src/translate/translateMultiple.ts:35); the kit's input !== null guard (kits/firestore-translate-text/src/translate/translateDocument.ts:44) routes it to translateSingle, and fix(firestore-translate-text): stop coercing non-string input before translation #3109's test pins that (tests/translate-document.test.ts:116) — decide/Note - issue decision(firestore-translate-text): null input routes to translateSingle instead of throwing #3142
• firestore-bigquery-export: EXCLUDE_OLD_DATA / USE_NEW_SNAPSHOT_QUERY_SYNTAX - extension accepted yes/no, kit defineBoolean accepts true only, so a migrated .env with yes silently reads as false - issue firestore-bigquery-export kit: EXCLUDE_OLD_DATA and USE_NEW_SNAPSHOT_QUERY_SYNTAX read 'yes' as false #3126 - decide/Note

Feature-scale (design first)

• firestore-bigquery-export: write-path buffering — the extension buffers in Cloud Tasks; the kit rethrows and can hot-loop (§1) — issue feat(firestore-bigquery-export): design write-path buffering #3031 — DECISION: reinstate the Cloud Tasks buffer (option D, migration safety) — feat(firestore-bigquery-export): reinstate the Cloud Tasks write buffer #3103 closed 2026-09-07 in favour of stack #3132, bottom to top: chore(firestore-bigquery-export): bump firebase-admin to ^14.2.0 #3127 (firebase-admin ^14.2.0), feat(firestore-bigquery-export): add the sync task enqueue module #3128 (enqueue module), feat(firestore-bigquery-export): add the sync queue params #3129 (queue params), feat(firestore-bigquery-export): reinstate the Cloud Tasks write buffer #3130 (the behaviour change), docs(firestore-bigquery-export): document failure handling and recovery #3131 (docs), all open @cabljac

Notes candidates (won't fix — differences to justify in Notes instead)

• No deploy-time status surface in kits (no setProcessingState equivalent) — firestore-bigquery-export §3d, firestore-translate-text, firestore-vector-search §9d
• billingRequired: true has no kit equivalent (firestore-translate-text, rtdb-limit-child-nodes)
• Event payload shape, if ruled intentional gen2 design — ruled NOT intentional in issue decision(kits): event payload shape {change, context} vs {data, params} #3027 (open); fix in fix(kits): restore the extensions' event payload shapes #3098

Minor / cosmetic (batchable)

• storage-resize-images: IS_ANIMATED select label reads True where the extension says Yes (kits/storage-resize-images/src/config.ts:189 vs extension.yaml:289-292) — issue fix(storage-resize-images): IS_ANIMATED select label is True, the extension says Yes #3123

Completed

Correctness / production-firing

• storage-resize-images: deletion risk — empty imageTypes → zero outputs counts as success → original deleted under on_success (§6) - fix(storage-resize-images): failed resize can delete the original image #3037 (merged)
• firestore-counter: deep-equal called without { strict: true } in the worker (§1) - fix(firestore-counter): compare worker metadata with strict deep-equal #3072 (merged)
• storage-resize-images: content-filter region reads FUNCTION_REGION and throws when absent; the extension fell back to us-central1 (§5) - fix(storage-resize-images): restore the us-central1 content-filter fallback #3090 (merged)
• firestore-vector-search: queryOnWrite prefilters cast unvalidated — the extension zod-parses them (§7b) - fix(firestore-vector-search): validate prefilters on the query onWrite path #3065 (merged)
• firestore-vector-search: queryOnWrite self-retrigger loop (§7) - fix(firestore-vector-search): stop queryOnWrite retriggering itself #3038 (merged; stored-request guard, self-heals the stale-overwrite race — supersedes fix(firestore-vector-search): guard queryOnWrite with the extension's status #3095, which is still open and should be closed)
• bigquery-firestore-export: Pub/Sub topic renamed ext- → kit-, update path rewrote notification_pubsub_topic (§4) - fix(bigquery-firestore-export): make the DTS notification topic configurable #3088 (merged; topic configurable via PUB_SUB_TOPIC, set it to the old ext- topic to preserve notifications across migration)
• firestore-bigquery-export: DATABASE_REGION used as function region — eur3/nam5/nam7 aren't Cloud Run regions → deploy hard-fails (§2) - fix(firestore-bigquery-export): stop using DATABASE_REGION as the function region #3066 (merged, live-verified on a nam5 database; the same conflation is still live in firestore-send-email: fix(firestore-send-email): DATABASE_REGION used as function region breaks multi-region deploys #3069 (open), tracked under Remaining parity work. NOTE: fix(firestore-bigquery-export): stop using DATABASE_REGION as the function region #3066's param removal partially reverted by fix(firestore-bigquery-export): place functions from DATABASE_REGION with a multi-region mapping #3101, which restores DATABASE_REGION as a placement param with the dual-region mapping, per the firebase-tools team's minimal-divergence decision and upstream bug Functions deploy: region resolution runs before param substitution, parameterized Firestore trigger database silently falls back to us-central1 firebase-tools#11020)

Migration / consumer breaks

• firestore-vector-search: OpenAI model changed — ada-002 → 3-small@512, incompatible with existing indexes (§2) — decision recorded in issue decision(firestore-vector-search): embedding model and dimension defaults #3029 (revert to the extension's defaults) — fix(firestore-vector-search): restore the extension's embedding defaults #3096 (merged)
• firestore-vector-search: gemini/vertex embedding dimensions changed — extension hardcoded outputDimensionality: 768 with no truncation; kit passes config.dimension and truncates the result (§5) — fix(firestore-vector-search): restore the extension's embedding defaults #3096 (merged)

Events gaps

• firestore-bigquery-export: onSuccess never published, and the kit README claims it is — doc bug, small standalone fix - docs(firestore-bigquery-export): stop claiming the kit publishes onSuccess and onCompletion #3071 (merged; doc-only, no code change needed)
• firestore-vector-search: events published only from handleEmbedOnWrite — nothing from the query/backfill/update/init paths — fix(firestore-vector-search): stop publishing events the extension never sent #3094 (merged) resolves issue fix(firestore-vector-search): publish events from all paths #3016 by REMOVING the kit-only events instead (the extension never published any; parity) @CorieW

Behavior divergence (fix or decide)

• firestore-bigquery-export: no onConfigure lifecycle equivalent (§3a) — DECISION: investigate — investigated: no gap, afterRedeploy covers it. firebase-tools hashes each endpoint as source+env+secrets, so an .env-only change marks the endpoint for update, which counts as a resource modification and fires afterRedeploy (release/lifecycle.js skips the hook only when nothing changed). The extension wired onUpdate and onConfigure to the same handler, and the kit wires afterRedeploy to the same idempotent setupBigQuerySync reconcile task, so behaviour is equivalent
• firestore-genai-chatbot: generation options now reach the model — DECISION: forward — README note in docs(kits): note that genai chatbot generation options now reach the model #3087 (merged)
• firestore-translate-text: new TranslationService per invocation — fresh client per event, performance (§5f) - fix(firestore-translate-text): construct the translation client once per process #3075 (merged)
• firestore-vector-search: vector-store error codes collapsed to unknown — the extension mapped 15 Firestore codes to HttpsError (§8) — DECISION: fix, parity — issue fix(firestore-vector-search): map vector-store errors to HttpsError codes #3015 — fix(firestore-vector-search): map vector-store errors to HttpsError codes #3093 (merged)
• firestore-send-email: TESTING env path gone — the kit cannot enter testing mode via env — issue fix(firestore-send-email): restore the TESTING env path #3107 — fix(firestore-send-email): restore the TESTING env path #3110 (merged) @CorieW
• firestore-translate-text: non-string input coerced — 42 → "42" reaches the API (§4b) — minor, decide — DECISION: fix, aim for parity — issue fix(firestore-translate-text): stop coercing non-string input before translation #3106 — fix(firestore-translate-text): stop coercing non-string input before translation #3109 (merged) @CorieW

Feature-scale (design first)

• firestore-counter: no client libraries (Android/iOS/Dart/node/web), shard format undocumented — closed as not planned (feat(firestore-counter): client libraries and shard format documentation #3033): migration only; the existing extension clients keep working against the unchanged shard format
• firestore-translate-text: backfill removed, along with the "only fill missing languages" semantics — DECISION: no fix — the extension's backfill never deploys (resource and DO_BACKFILL commented out in its yaml), so no-backfill is parity — issue feat(firestore-translate-text): design backfill #3032
• firestore-bigquery-export: user-facing tooling absent — import, gen-schema-view, cross-project scripts, guides — DECISION: reference existing extension scripts/tooling — issue feat(firestore-bigquery-export): user-facing tooling #3034

Notes candidates (won't fix — differences to justify in Notes instead)

• rtdb-limit-child-nodes: NODE_PATH rename (Node.js reserves the name)

Minor / cosmetic (batchable)

• firestore-bigquery-export: logs.start() called with no argument → logs undefined (§4) - chore(firestore-bigquery-export): drop unused config parameter from logs.start #3039 (merged)
• firestore-vector-search: custom-endpoint content-type check dropped (§4c) - fix(firestore-vector-search): reject non-JSON responses from the custom embeddings endpoint #3042 (merged)
• firestore-send-email: formatZodError invalid_string branch dropped - fix(firestore-send-email): restore the invalid_string branch in formatZodError #3040 (merged)
• storage-resize-images: BLOCK_NONE accepted where the extension threw (§4); cacheControlHeader: "" set literally (§7) - fix(storage-resize-images): reject BLOCK_NONE and treat empty Cache-Control as unset #3044 (merged)
• bigquery-firestore-export: dropped log helpers; MAX_STALENESS doc example 8h → 4h - chore(bigquery-firestore-export): restore dropped log helper and MAX_STALENESS doc example #3045 (merged)
• delete-user-data: node-fetch@2 where the extension used global fetch - chore(delete-user-data): replace node-fetch with the Node global fetch #3041 (merged)
• firestore-translate-text: dead backfill remnants (filterLanguagesFn, unused log helpers) - chore(firestore-translate-text): delete dead backfill remnants from the kit #3043 (merged)
• firestore-genai-chatbot: local SafetySetting type (no enum check); PROJECT_ID error text - fix(firestore-genai-chatbot): type safety settings against the SDK enums and restore the PROJECT_ID error text #3046 (merged; whole minor-cleanups batch issue chore(kits): minor parity cleanups #3036 now complete)

Coverage

• bigquery-firestore-export: 1330 unit + 3170 E2E lines → 550 unit; ensureNotificationTopic untested - test(bigquery-firestore-export): port legacy unit coverage into the kit #3056 (merged; 19 → 65 tests)
• firestore-genai-chatbot: emulator E2E + logger/overrides/config suites gone - test(firestore-genai-chatbot): port missing coverage from the legacy extension #3058 (merged; incl. emulator flow test, now run in PR CI via ci(kits): run emulator-gated kit suites on pull requests #3070)
• firestore-counter: no emulator tests - test(firestore-counter): port the active legacy emulator tests #3054 (merged; run in PR CI via ci(kits): run emulator-gated kit suites on pull requests #3070)
• delete-user-data: lazy getContext() path untested - closed by fix(delete-user-data): resolve the RTDB client on first use #2955 and test(delete-user-data): pin context memoization and client wiring #3055 (both merged)
• firestore-send-email: 2540 → 483 lines - test(firestore-send-email): port the legacy unit suites into the kit #3057 (merged; 121 tests, coverage audit found no decrease vs the legacy suite)

[CorieW]

Kit: bigquery-firestore-export

Parity analysis: bigquery-firestore-export

Kit: kits/bigquery-firestore-export
Upstream extension: GoogleCloudPlatform/firebase-extensions/bigquery-firestore-export (v0.2.2)
Out of scope: Kits-vs-Extensions API shape, and v1 → v2 Cloud Functions mechanics. Everything below is extension-specific or kit-specific logic, params, roles, APIs, or test coverage.

Summary

• Regression — transfer-config service account dropped. The scheduled query runs as the DTS caller identity rather than the kit service account (§1.1).
• Regression — soft failures became hard failures. Three cases the extension reported as PROCESSING_COMPLETE now throw, and retry (§1.7).
• Fix — arrays stay arrays. The extension turned ARRAY/REPEATED columns into index-keyed maps (§1.2).
• Fix — config validation. The kit fails fast instead of creating a broken DTS config (§1.9).
• Coverage loss. 1330 lines of unit tests and 3170 lines of E2E dropped to 550 lines of unit tests, with no E2E (§7).
• Untested and behaviourally new: ensureNotificationTopic, including its gRPC code 6 race swallow.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Transfer-config service account	Creates the DTS config with serviceAccountName = ext-${instanceId}@${projectId}.iam.gserviceaccount.com	serviceAccount exists on the config type but configFromEnv() never sets it, so it is always undefined and serviceAccountName is omitted — see src/config.ts and src/dts.ts:88	Regression. The scheduled query runs as the DTS caller identity rather than the kit service account, so data-access permissions differ.
2	Arrays in BigQuery rows	Recursion does {...row} on arrays, so an array becomes an index-keyed map in Firestore. The upstream test passes only because obj[0] still indexes a map	Array.isArray branch maps element-wise, so arrays stay arrays — src/helper.ts	Kit fixes an upstream bug. Document shape differs for any ARRAY/REPEATED column.
3	Link an existing config	config.transferConfigName is hardcoded to undefined and no param exists, so the whole link branch is dead code	TRANSFER_CONFIG_NAME param is exposed and the branch is live	Kit-only feature.
4	Pub/Sub topic name	ext-${instanceId}-processMessages	kit-${instanceId}-processMessages	Existing DTS configs point at the old topic; the kit's update path rewrites notification_pubsub_topic.
5	Topic provisioning	Never created in code — the extension framework provisions it from the eventTrigger resource	ensureNotificationTopic() runs first on every upsert: exists(), then createTopic(), tolerating gRPC code 6 (ALREADY_EXISTS) — src/handlers.ts	Kit-only. Requires pubsub.googleapis.com, which the kit declares and the extension does not.
6	Update flow API calls	updateTransferConfig(), then a second getTransferConfig() re-read, and the re-read is stored. If the re-read returns null: PROCESSING_COMPLETE and no Firestore write	Stores the object returned by updateTransferConfig() directly — one call	The extension can silently skip the Firestore write; the kit cannot.
7	Failure reporting	runtime.setProcessingState(...) across 10 call sites, each with its own user-facing message	No lifecycle runtime — all failures throw	See 7a–7c.
7a	Linked config not found	PROCESSING_COMPLETE and return, i.e. reported as success	throw new Error("Transfer config not found: …")	The kit fails the deploy where the extension reports OK.
7b	Partitioning-field removal	Caught and reported as PROCESSING_COMPLETE with the error text — swallowed	Throws, so the task retries five times and then dead-letters	The kit turns a soft warning into a hard failure plus retries.
7c	Existing doc missing name	PROCESSING_FAILED, then throws a different message ('Existing transfer config document missing name field')	Single throw, and also rejects a non-string name via a typeof check	Kit is stricter.
8	Retries	v1 onPublish with no failurePolicy, so no retry. Task queue uses defaults	onMessagePublished({retry: true}), and the task uses {maxAttempts: 5, minBackoffSeconds: 30} — src/index.ts	The kit reprocesses failed messages. A message for a non-associated config now throws and retries repeatedly.
9	Config validation	None. datasetId, tableName, queryString, displayName, and schedule are all ?: string, and undefined flows into the DTS request	resolveConfig() trims each and throws "<field> must be a non-empty string.", and throws on an unsupported logLevel — src/export-config.ts	The kit fails fast on first invocation instead of creating a broken DTS config.
10	BigQuery client	new BigQuery() per query with no projectId, so it uses the ADC default project; only the query string is qualified with config.projectId	A single injected new BigQuery({projectId: config.projectId})	Job and billing project differ when the ADC default is not the configured project.
11	updateMask paths	'params' is pushed up to three times and duplicates are sent	[...new Set(updateMask)]	Cosmetic on the wire; the kit asserts the dedupe in a test.
13	Existing-config query	.where(...).get() fetches all matches and checks results.size > 0	.where(...).limit(1)	Fewer reads. Neither warns when multiple configs match; upstream has a TODO for it.
14	Init timing	admin.initializeApp() and logs.init() run at module load	Lazy getContext() on first invocation, guarded by getApps().length === 0	The kit is importable without side effects via the ./lib entry point.

Logging

Extension	Kit
pubsubMessage / pubsubMessageHandled dump the whole message JSON (JSON.stringify(…, 2)) on every message	logs.start() / logs.complete(), with no payload
init() logs the full config, obfuscating smtpConnectionUri and smtpPassword — copy-paste from firestore-send-email, so queryString is logged in full	Obfuscates queryString; no SMTP keys
Mostly logger.debug with interpolated strings	Mostly logger.info / logger.error with structured metadata objects
logs.writeRunResultsToFirestore(runId), logs.start(), logs.invalidResourceName()	Dropped
logs.error() is called before throwing on a non-associated config	Logged by the handleMessagePublished catch instead
Partitioning error text ends "…you must create a new transfer config with the desired partitioning settings."	Ends "…create a new transfer config with the desired setting." — the string differs, so prefix matching via PARTITIONING_FIELD_REMOVAL_ERROR_PREFIX still works but exact matching does not

Params

Param	Extension	Kit
LOCATION	select, 22 regions, default us-central1, required, immutable	Absent
DISPLAY_NAME	Required, immutable	Required at resolve time, mutable — but DTS displayName is never added to the update mask, so edits silently no-op
PARTITIONING_FIELD	Optional	Optional and trimmed, so a whitespace-only value becomes undefined
LOG_LEVEL	select with lowercase values but default: INFO (uppercase) — a mismatch	select, default info; normalizeLogLevel() lowercases and falls back to info
TRANSFER_CONFIG_NAME	—	Kit-only, default ""
INSTANCE_ID	Implicit EXT_INSTANCE_ID	Explicit required defineString("INSTANCE_ID") with no default

Roles and APIs

API	Extension	Kit
pubsub.googleapis.com	✗	✓

Kit drops the per-role reason strings; only requiresRole(role) is called. API reasons are kept.

[CorieW]

Kit: delete-user-data

Parity analysis: delete-user-data

Kit: kits/delete-user-data
Upstream extension: delete-user-data (functions/src/ + extension.yaml)
Out of scope: Kits-vs-Extensions API differences, and v1 → v2 trigger upgrades. Everything below is extension-specific or kit-specific logic, params, roles, APIs, or testing.

Summary

• Fix — search publishes are awaited. The extension fire-and-forgets, so messages can be lost when the instance freezes (§3).
• Fix — empty searchFields no longer throws. The extension builds new FieldPath("") and fails handleDeletion (§2).
• Coverage net-positive — the extension's 6 emulator-driven suites (24 cases, 647 lines) become 9 vitest suites (84 cases, 1498 lines), trading emulator fidelity for injectable-context unit tests. The RTDB gate is now covered (85 cases); the lazy getContext() path is not.

Runtime behaviour

#	Area	Extension	Kit	Impact
2	hasValidUserPath with empty searchFields	helpers.ts: searchFields = "" → "".split(",") → [""] → new FieldPath("") throws → handleDeletion fails	Short-circuits searchFields.length === 0 to false with no document read, and applies .filter(Boolean) to segments (trailing-comma safe). Receives searchFields as an argument rather than reading global config	Kit fixes an upstream crash.
3	Search publish	search.ts calls topic.publish(...) unawaited inside a for loop — fire-and-forget, messages can be lost when the instance freezes	Awaits publishSearch per collection	Kit fixes message loss. Slower, correct.
4	Topic path fallback	Always builds projects/${GOOGLE_CLOUD_PROJECT || PROJECT_ID}/topics/..., producing a literal projects/undefined/... when unset	topicPath() prefers projectID.value(), falls back to GOOGLE_CLOUD_PROJECT, then PROJECT_ID, then the bare topic name	Kit degrades to a bare topic name instead of a malformed path.
5	Topic names	ext-${EXT_INSTANCE_ID}-discovery / -deletion, fixed	kit-${INSTANCE_ID}-discovery / -deletion, user-overridable via new params	Cross-instance topic collision is now possible if misconfigured.
6	Client initialisation	Single module-load initializeApp + getFirestore + Eventarc channel	Lazy memoized getContext(), admin.apps.length === 0 guard, databaseURL conditionally spread. Eventarc channel held in module state in events.ts via setupEventChannel()	—
7	fetch implementation	Global fetch	node-fetch@2. Also guards !searchFunction with an early return inside runCustomSearchFunction	—

Params

Param	Extension	Kit
INSTANCE_ID	—	Kit-only. defineString, required, no default. Must match this instance's key in the instances map
DISCOVERY_TOPIC_NAME / DELETION_TOPIC_NAME	—	Kit-only. defineString, default expr template kit-${instanceId}-…, so topic names are now user-settable
ENABLE_AUTO_DISCOVERY	select yes/no, default no, runtime === "yes". The yaml uses unquoted value: yes — a YAML 1.1 boolean, and a latent extension bug	defineBoolean, default false — type change, so an extension .env value of yes will not parse
AUTO_DISCOVERY_SEARCH_DEPTH	string, default 3, validation: ^[0-9] (invalid key — no validation applied), parseInt, so junk yields NaN	defineInt, same default — real numeric typing
AUTO_DISCOVERY_SEARCH_FIELDS	yaml default id,uid,userId, but runtime falls back to "" when the env var is absent	Default id,uid,userId in both the param and resolveDeleteUserDataConfig, so the default is applied twice
FIRESTORE_DATABASE_ID	Default (default), required	Default (default), optional

The kit adds a second resolution layer: configFromEnv() then resolveDeleteUserDataConfig(). Defaults are declared in both, so a programmatic caller of resolveDeleteUserDataConfig gets the same defaults as the env path.

Roles and APIs

Kit declares roles via a requiresRole() loop in src/index.ts. Kit README warns that setting a custom runtime service account conflicts with the CLI's automatic role grant (Firebase CLI 15.23.0 or later).

Events

The kit holds the Eventarc channel in module state in events.ts via setupEventChannel() rather than creating it at module load.

[CorieW]

Kit: firestore-bigquery-export

Parity analysis: firestore-bigquery-export

Kit: kits/firestore-bigquery-export
Upstream extension: firestore-bigquery-export
Out of scope: Kits-vs-Extensions API differences, and v1 → v2 function upgrades. Everything below is extension-specific or kit-specific logic, params, roles, APIs, or testing.

Summary

• Write-path failure handling is the biggest divergence. The extension buffers durably in Cloud Tasks and swallows terminal failures (silent row loss); the kit rethrows and relies on trigger retry, so it never loses a write but can hot-loop on a persistent BigQuery error (§1).
• Deploy bug — region. The kit uses DATABASE_REGION for the functions themselves, and that list includes the Firestore multi-regions eur3 / nam5 / nam7, which are not valid Cloud Run regions (§2).
• DATASET_LOCATION immutability lost — a changed value on redeploy silently mismatches the existing dataset (§5).
• yes/no param values no longer parse as booleans, so an .env lifted from an extension install silently reads false (§5).
• User-facing tooling (import, gen-schema-view, cross-project access scripts, guides) is absent from the kit.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Write-path failure handling	Buffers durably in Cloud Tasks	Relies on trigger retry	Biggest divergence. The extension loses the write if enqueue fails; the kit never loses it but can hot-loop on a persistent BigQuery error. See 1a–1e.
1a	Trigger retry	onDocumentWritten with no retry → no runtime retry	retry: true → runtime replays the event	—
1b	On inline BQ write failure	attemptToEnqueue → Cloud Tasks syncBigQuery	ensureInitialized() self-heal + one re-write	—
1c	Retry tuning	MAX_ENQUEUE_ATTEMPTS (default 3), 2^n*100ms capped at 5s + jitter; syncBigQuery maxAttempts 5, minBackoff 60s, maxConcurrentDispatches 500, maxDispatchesPerSecond param	n/a — no syncBigQuery function at all (src/index.ts)	Extension exports 4 functions, kit exports 3.
1d	Terminal failure	Error swallowed — logs + onError event, handler resolves, logs.complete() runs	Rethrows → Eventarc/Functions retry	Silent row loss in the extension.
1e	Empty-data guard	Would throw in getChangeType(undefined)	if (!data) return; (src/handlers.ts:131)	Kit fixes an upstream crash.
2	Function region	Function region = extension install LOCATION; trigger region = ${DATABASE_REGION}, separate	Single region = DATABASE_REGION for the trigger and both task functions (src/index.ts:119-121)	Real bug. DATABASE_REGION options include the Firestore multi-regions eur3, nam5, nam7, which are not valid Cloud Run / Cloud Functions regions. Kit deploy breaks for those three values; the extension does not.
3	Provisioning / lifecycle	Extensions-platform lifecycle hooks with status reporting	Kit deploy hooks, no status reporting	See 3a–3e. Both set skipInit: true on the tracker config.
3a	Hooks	onInstall→initBigQuerySync, onUpdate+onConfigure→setupBigQuerySync	afterFirstDeploy→init, afterRedeploy→setup	No onConfigure equivalent in the kit.
3d	Status reporting	getExtensions().runtime().setProcessingState("PROCESSING_COMPLETE", …)	None	No deploy-time status surface.
3e	Idempotence guard	None — calls initialize() raw each dispatch	createEnsureInitialized — once-per-instance, shared in-flight promise, resets on failure (src/init.ts)	Kit avoids duplicate initialisation.
4	logs.start()	Logs the full config object every invocation	start() takes an optional arg and is called with none → logs undefined. Config is logged once via logs.init(config)	—
5	logs.complete()	Always reached, since failures are swallowed	Only on success	—
7	Config resolution	Resolved at module load from process.env	Resolved lazily on first invocation (getHandlerContext(), memoized)	Deploy discovery can import the module without resolving params.

Params

Param	Extension	Kit
MAX_DISPATCHES_PER_SECOND	yaml default 100, regex 1–500	Absent — no queue to rate-limit
MAX_ENQUEUE_ATTEMPTS	Default 3, regex 1–10	Absent
IMPORT_COLLECTION_PATH, BACKUP_TO_GCS, BACKUP_GCS_BUCKET, INSTANCE_ID/backupDir, maxDispatchesPerSecond	Dead in config.ts — no yaml param	Absent
USE_NEW_SNAPSHOT_QUERY_SYNTAX	select yes/no, default no, compared === "yes"	defineBoolean, default false — equivalent default, but yes/no does not parse as a boolean → silently false, so an extension .env cannot be reused
EXCLUDE_OLD_DATA	select yes/no	defineBoolean — same .env break
DATASET_LOCATION	immutable: true	No immutability — a changed value on redeploy silently mismatches the existing dataset
MAX_STALENESS	Documented example INTERVAL "8:0:0" HOUR TO SECOND, no validation	Documented example 0-0 0 4:0:0, no validation

Kit's configFromEnv doc
notes deploy-discovery relies on the TABLE_PARTITIONING=NONE default to avoid throwing during
the analysis pass — the extension has no such constraint.

Roles and APIs

Extension declares APIs in extension.yaml; kit via requiresAPI().

Events

	Extension	Kit
Types published	both firebase.extensions.firestore-counter.v1.* (legacy back-compat) and …firestore-bigquery-export.v1.*	only …firestore-bigquery-export.v1.*
onError	yes (enqueue failure only)	yes (self-heal failure)
onSuccess	yes — only on syncBigQuery dispatch, never on the happy inline path	never published
Declared-but-dead	firebase.extensions.big-query-export.v1.sync.start in extension.yaml, never published	—

Kit README.md claims onSuccess/onCompletion are published. Code disagrees — doc bug.

[CorieW]

Kit: firestore-counter

Parity analysis: firestore-counter

Kit: kits/firestore-counter
Upstream extension: firestore-counter (the Distributed Counter Firebase Extension)
Out of scope: Kits-vs-Extensions API differences (.env/defineString vs extension.yaml params, firebase.json kit stanza vs extension.yaml resources), and the Functions v1 → v2 upgrade.

The core algorithm — aggregator.ts, planner.ts, controller.ts, worker.ts — is a faithful
port. Constants are all preserved: 200 in-line aggregation limit, 60000 ms continuous-aggregation
timeout, 45000 ms worker timeout, 100 shards per worker round, 499 query cap. Everything below is a
real behavioural delta.

Summary

• Correctness risk — loose equality in the worker. deep-equal is called without { strict: true }, so the worker can fail to notice its metadata document changed (§1).
• Largest parity gap — no client libraries. The extension ships Android, iOS, Dart, node, and web clients; the kit ships none, and does not document the shard format.
• Event payload shape changed from { change, context } to { data, params } — any consumer reading context.params breaks (§5).
• No emulator tests at all. Transaction contention, collectionGroup ordering, and onSnapshot timing are only simulated.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Worker equality check	util.isDeepStrictEqual	deep-equal@1.1.2 called without { strict: true }, so comparisons are ==-based and prototypes are not checked — src/worker.ts:118, src/worker.ts:152, src/worker.ts:246	Correctness risk. A type-only metadata change ("1" vs 1, a plain object vs a Timestamp instance) now compares equal, so the worker fails to detect that its metadata document changed. It keeps aggregating a slice it no longer owns, or writes stats that race the controller instead of bailing out. Fix: pass { strict: true } at all three call sites.
3	Deferred initialization	Initializes the admin app, the Eventarc channel, and the Firestore client at module load	Defers all three to the first invocation via getHandlerContext() (src/index.ts:58), guarding app creation with getApp()	The Eventarc channel is not created until a trigger first fires.
5	Event payload shape	onStart / onCompletion publish { change, context }	Publishes { data, params } and { params } (src/handlers.ts:62, src/handlers.ts:74)	Breaking. Any Eventarc consumer reading context.params breaks. A kit choice, not forced by v2 — event.params could have been mapped onto a context-shaped payload.
6	UUID source	crypto.randomUUID()	uuid.v4() in aggregator.ts and in ShardedCounterWorker.cleanupPartials	Same output shape; adds a runtime dependency for no functional gain.

Params

Both params are in parity (defaults, validation, labels, descriptions, examples).

• configFromEnv() does Number(SCHEDULE_FREQUENCY), yielding NaN silently
  for non-numeric input. The value is dead at runtime: src/index.ts schedules
  from the expr template over the raw param string, not from the parsed
  number.
• scheduleExpression() is exported from src/export-config.ts but unused by
  the kit's own index.ts, leaving two sources of truth for the schedule
  string.

Events

See §5 — payload shape changed from { change, context } to { data, params }.

Deploy and resources

The extension's in-code trigger paths are placeholders overridden by
extension.yaml. The kit correctly mirrors the yaml paths, not the code:

• onWrite: {collection}/{counter=**}/_counter_shards_/{shardId},
  maxInstances: 1, timeoutSeconds: 120
• worker: ${INTERNAL_STATE_PATH}/workers/{workerId}, no instance cap
• controllerCore: every ${SCHEDULE_FREQUENCY} minutes, maxInstances: 1

[CorieW]

Kit: firestore-genai-chatbot

Parity analysis: firestore-genai-chatbot

Kit: kits/firestore-genai-chatbot
Upstream extension: GoogleCloudPlatform/firebase-extensions/firestore-genai-chatbot (v0.0.19)
Out of scope: Kits-vs-Extensions API differences (extension.yaml params vs firebase-functions/params, requiresRole / requiresAPI vs the yaml roles / apis blocks), and the v1 → v2 functions upgrade (functions.firestore.document().onWrite → onDocumentWritten).

Summary

• Significant — generation options now reach the model. TEMPERATURE / TOP_P / TOP_K / CANDIDATE_COUNT were inert in the extension; the kit forwards them (§1).
• Behaviour change — Vertex model location fallback. null no longer means "same as the Cloud Functions region" (§3).
• Startup env-var validation removed entirely (validateRequiredEnvVars()).
• Emulator end-to-end coverage lost, along with the logger, overrides, and config-validation suites.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Generation options passed to the model	generate_chat_response.ts builds requestOptions with only history, context, maxOutputTokens, safetySettings	src/generate-chat-response.ts also passes temperature, topP, topK, candidateCount	Significant. In the extension, TEMPERATURE / TOP_P / TOP_K / CANDIDATE_COUNT never reach the Google AI or Vertex clients. Those clients are only selected when candidateCount > 1, so the extension asked the API for one candidate and then wrote a single-element candidates array — CANDIDATE_COUNT was effectively inert. The kit forwards them.
2	candidates field gate	shouldAddCandidatesField computed once at module scope from config only	computed per request from the post-override requestOptions.candidateCount	A per-discussion candidateCount override can now enable or disable the candidates field. The extension ignored overrides for this decision.
3	Vertex model location fallback	VERTEX_AI_MODEL_LOCATION == 'null' ? process.env.LOCATION : … — falls back to the Cloud Functions region	=== "null" ? undefined in src/config.ts	Behaviour change. null no longer means "same as the Cloud Functions location"; the SDK / genkit plugin default applies instead (us-central1, or GOOGLE_CLOUD_LOCATION). The kit has no LOCATION param to fall back to.
4	Vertex SDK	@google-cloud/vertexai VertexAI → client.preview.getGenerativeModel() → generateContentStream(), response aggregated	@google/genai GoogleGenAI({ vertexai: true }) → models.generateContent()	No streaming call, and the GA surface rather than preview. Same final text.
5	Vertex empty-candidate handling	filters candidates that have text, then indexes candidates[0] with non-null assertions → TypeError when everything is filtered out	maps then filters, throws "No text candidates returned"	The kit writes a clean status.error; the extension wrote a raw TypeError message.
6	Missing / invalid response	result.response! written straight to Firestore	throws "No response returned from generative client." / "No candidates returned from generative client."	Different status.error text for the blocked or empty response case.
7	Missing createTime in writeStartEvent	change.after.createTime! (writes undefined)	throws "Missing document createTime for start event.", outside the try/catch → function error and retry, no ERROR state written	Divergent failure mode.

Params

Param	Extension	Kit
LOCATION	Required, immutable, 20-region select; also surfaced as config.location	Removed. The function region is now whatever the functions codebase defaults to — the kit's own test asserts no region in the deploy options. Also causes §3
API_KEY	type: secret, required: false — Vertex users leave it blank	defineSecret("API_KEY"), always present in secrets: [...], so Vertex-only deployments must still provision an API_KEY secret
ENABLE_DISCUSSION_OPTION_OVERRIDES	select yes / no, compared === 'yes'	defineBoolean (true / false) — not a lift-and-shift .env, a value of yes will not parse as true
ENABLE_GENKIT_MONITORING	select yes / no	defineBoolean — same .env break
COLLECTION_NAME	yaml default generate; code fallback users/{uid}/discussions/{discussionId}/messages	Default generate in both the param and resolveConfig, so the programmatic default changed
TOP_K, CANDIDATE_COUNT, MAX_OUTPUT_TOKENS	Parsed with parseInt	Parsed with Number(). TOP_K=3.7 → extension 3, kit 3.7. TOP_K=5abc → extension 5, kit NaN (both pass the shared unanchored regex)
EXT_INSTANCE_ID / instanceId	Required env var, part of Config	Removed
PROJECT_ID	process.env.PROJECT_ID	getProjectId() reading FIREBASE_CONFIG, so it throws "FIREBASE_CONFIG is not set" instead of a missing-var error
Startup validation	validateRequiredEnvVars() throws on a missing MODEL / LOCATION / PROJECT_ID / EXT_INSTANCE_ID at module load	Removed — no fail-fast on misconfiguration
Invalid provider	getSafetySettings() throws Invalid Provider: X at module load	No config-time check; fails later in initializePlugin() or getGenerativeClient(), so the error surfaces per message rather than at cold start
SafetySetting type	SDK types from @google-cloud/vertexai / @google/generative-ai	Local { category: string; threshold: string } — no compile-time enum check on category or threshold

Deploy and resources

• No region configured on the kit function (the by-design LOCATION removal); the extension sets no memory or maxInstances either.
• The kit adds an explicit lazy initializeApp() and a lazily memoised resolved
  config; the extension relied on module-scope singletons.

[CorieW]

Kit: firestore-send-email

Parity analysis: firestore-send-email

Kit: kits/firestore-send-email
Upstream extension: firestore-send-email (published extension, as of branch kits)
Out of scope: Kits-vs-Extensions API differences, and v1 → v2 function upgrades. Everything below is extension-specific or kit-specific logic, params, roles, API surface, or testing.

Summary

• Coverage loss — 2540 → 483 lines. Essentially all payload-validation, SendGrid-transport, SMTP-credential, and end-to-end coverage is gone.
• Regression — SendGrid + AUTH_TYPE=OAuth2 sends fail. Secret gating forces apiKey: undefined, so setApiKey is never called.
• Five extension bugs fixed in the kit: init-failure poisoning, non-existent template, waiter leak, lease-check crash, missing change guard.
• nodemailer major-version drift — ^9.0.1 (extension) vs ^7.0.5 (kit).

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Init-failure poisoning	functions/src/index.ts:60 sets initialized = true before await transportLayer(). If the transport throws, every later invocation skips init and runs with db/transport undefined	Nulls initialization in .catch(), so the next invocation retries	Kit fixes an upstream bug.
2	Non-existent template	templates.ts does const templateExists = this.checkTemplateExists(name) without awaiting → always truthy → never rejects → falls through to t.attachments on undefined → TypeError	Awaits it and throws a clean Tried to render non-existent template '<name>'	Kit fixes an upstream bug.
3	Waiter leak	Never clears this.waits after resolving, so every snapshot re-resolves the entire history	Resets this.waits = []	Kit fixes an upstream bug.
4	Lease-check crash	Calls payload.delivery.leaseExpireTime.toMillis(). A doc in PROCESSING without leaseExpireTime throws a TypeError, caught by the outer handler and reported as Unhandled error occurred during processing	Uses ?. — no throw, no state change	Kit fixes an upstream bug.
5	Missing change guard	Dereferences change.before.exists unguarded	if (!change) return null	Kit fixes an upstream bug.
6	OAuth2 error reporting	Wraps setupOAuth2 in try/catch and reports "Error setting up OAuth2 transport"	Propagates the original nodemailer error	Different user-facing error text.
7	OAuth2 success log	Logs "OAuth2 transport setup successfully"	Not logged	—
8	logs.init() timing	Runs at module load and obfuscates all five secret-bearing fields to "<omitted>" unconditionally	Runs inside lazy init and emits undefined for unset secrets	Kit logs distinguish set from unset.
9	templates.render(name, data)	Passes a possibly-undefined value	Passes template.data || {}	—
10	SendGrid transport	Non-null assertions, so a present-but-empty key pushes value: undefined into msg.content	Skips watchHtml / messageId / icalEvent when falsy	Kit avoids the malformed content entry.
12	formatZodError	Has a case "invalid_string" branch → Field '<path>' must be a valid email address	Branch dropped, so those issues fall through to the default message	Different validation error text.

Params

Param	Extension	Kit
OAUTH_PORT	type: string, default 465, parseInt at read, so non-numeric yields NaN	defineInt, default 465 — rejects non-numeric at deploy
TESTING	Not declared in extension.yaml; read as process.env.TESTING === "true" → localhost:8132 transport	Not read from env at all; only settable programmatically via SendEmailConfig.testing, so the kit's env path cannot enter testing mode

TESTING verification: the string appears only in firestore-send-email/functions/src/config.ts:30,
its test, and compiled lib/. Nothing in _emulator/, nothing in extension.yaml.

Kit-only param logic

• resolveConfig trims and maps empty→undefined for every optional string. The
  extension passes raw env values through untouched.
• Secret resolution is gated on authType: with OAuth2, smtpPassword is forced to
  undefined; with UsernamePassword, the three OAuth secrets are forced to undefined.
  The extension always reads all four from env.
  • Consequence: a SendGrid URI combined with AUTH_TYPE=OAuth2 makes the kit pass
    apiKey: undefined to SendGridTransport, so setApiKey is never called and sends
    fail. The extension uses SMTP_PASSWORD and works. isSendGrid() is evaluated
    before auth type in both.
• secretParamsForAuthType() (src/config.ts:131) throws on an unknown AUTH_TYPE, but is
  dead code — only tests call it. src/index.ts binds all four secrets unconditionally.

Events

The extension declares seven event types in extension.yaml, so the channel
is provisioned at install time. The kit publishes only when EVENTARC_CHANNEL is set by
hand, and offers no allow-list param.

Deploy and resources

Function region. The extension's yaml sets only triggerRegion: ${DATABASE_REGION}
and leaves the function location undeclared. The kit sets region: DATABASE_REGION for
the function itself.

[CorieW]

Kit: firestore-translate-text

Parity analysis: firestore-translate-text

Kit: kits/firestore-translate-text
Upstream extension: firestore-translate-text
Out of scope: Kits-vs-Extensions API differences, and v1 → v2 Cloud Functions upgrades. Everything below is extension-specific or kit-specific logic, params, roles, APIs, or testing.

Summary

• Largest functional gap — backfill removed entirely, along with the "keep existing translations, only fill in missing languages" semantics (§1).
• Fix — translateMultiple no longer hangs. The extension's new Promise(async …) never settles on a thrown error; the kit propagates it (§4).
• Performance regression — a new TranslationService per invocation, so a fresh v2.Translate / genkit() client is built on every event (§6).
• Vertex AI region can differ from the extension's, since the kit reads FUNCTION_REGION and falls through to the genkit default when unset (§3).
• Coverage net-positive — 27 tests across 3 files → 89 across 10, minus backfill.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Backfill	Present in code with lifecycle hooks	Removed entirely	Largest functional gap. The extension's backfill resource and DO_BACKFILL param are commented out in extension.yaml, so it never deploys — but the code path and hooks are present. The kit also dropped the "keep existing translations, only fill in missing languages" semantics. See 1a–1d.
1a	Task-queue function	fstranslatebackfill, DOCS_PER_BACKFILL = 250, paging via getFunctions().taskQueue, setProcessingState COMPLETE / WARNING / FAILED	None	—
1b	Backfill translation paths	translateDocumentBackfill, translateSingleBackfill, translateMultipleBackfill, BulkWriter writes, partial-failure throw	None	—
1c	filterLanguagesFn	Used to skip already-translated languages during backfill	Method survives on TranslationService but has zero callers	Dead code in the kit.
1d	Config / logs	config.doBackfill (hardcoded false), logs.enqueueNext, logs.backfillComplete, logs.documentFoundNoInput, lifecycleEvents	None — the log helpers still exist in logs/, unused	Dead code in the kit.
2	Vertex AI region	vertexAI({ location: process.env.LOCATION! }) — always the extension's install location	vertexAI(config.region ? { location: config.region } : {}) — uses FUNCTION_REGION, and when unset falls through to the genkit default (us-central1) rather than the deployment region	A Vertex-backed install can hit a different regional endpoint than the extension would. The projectId swap (process.env.PROJECT_ID → projectID.value()) is equivalent.
3	Error handling in translateMultiple	Wraps each task in new Promise(async (resolve) => …) (translate/translateMultiple.ts:39). If the async executor throws, the rejection is unhandled and the promise never settles — await fn() hangs until the function times out	Plain async () => {…} tasks, so the error propagates, is caught in handlers.ts, and produces logs.error + recordErrorEvent + a completion event	Kit fixes a hang. Changes observable behaviour on translation failure for object/array inputs.
4	Null and non-string input	Raw values flow through	Coerced and re-routed	See 4a–4c.
4a	null routing	Checks typeof input === "object", so null routes into translateMultiple and Object.entries(null) throws	Adds && input !== null, routing null to translateSingle	Only reachable on the update path — create is guarded by if (input).
4b	Coercion	Passes the raw value	translateSingle(String(input), …)	A document with input: 42 sends 42 to the Translate API under the extension, "42" under the kit.
4c	Logging	Logs the raw value	Logs String(value) in translateMultiple	—
5	Initialisation timing and client lifetime	Everything at module load, one shared client	Lazy per-event context, new client per invocation	See 5a–5f.
5a	Init site	initializeApp(), setupEventChannel(), logs.init(config) and TranslationService all at module load	Lazy getContext() on the first event	—
5b	App creation	Unconditional initializeApp()	ensureDefaultApp() reuses an existing default app	—
5c	Missing Google AI key	Cold-start crash	Throws on first invocation, uncaught (outside handleDocumentWrite's try)	Failure surfaces later and differently.
5d	Config logging	Once per instance	On the first event	—
5e	Secret read	At module load	Only when useGenkit	—
5f	TranslationService lifetime	One module-level singleton	New instance per invocation (handlers.ts) — fresh v2.Translate / genkit() client each event	Performance regression relative to the extension.

Params

Param	Extension	Kit
TRANSLATION_PROVIDER	required: true, type: select, no default	defineString + select, no default — the CLI prompts, matching the extension. Only a programmatic/emulator caller with an empty value falls back to "translate" in resolveTranslateConfig
GOOGLE_AI_API_KEY	type: secret, required: false	defineSecret bound as secrets: [googleAiApiKey] on the trigger, so the secret must exist at deploy even for the translate provider
LOCATION	System param, feeds the Vertex AI plugin	Absent — uses process.env.FUNCTION_REGION. See §2
DO_BACKFILL	Commented out	Absent

Roles and APIs

Extension declares billingRequired: true; kit has no equivalent declaration.

Events

• Payload content differs: the extension publishes { change, context }, the kit
  publishes { data, params }. Consumers of onStart / onCompletion see a
  different shape.
• The kit returns early on !event.data without emitting start or completion
  events; the extension always emits both.
• The extension's events.recordErrorEvent(err) in the main catch is not
  awaited; the kit awaits it.

[CorieW]

Kit: firestore-vector-search

Parity analysis: firestore-vector-search

Kit: kits/firestore-vector-search
Upstream extension: firestore-vector-search v0.1.3 (GoogleCloudPlatform/firebase-extensions/firestore-vector-search)
Out of scope: Kits-vs-Extensions API surface differences, and Cloud Functions v1 → v2 upgrades. Everything below is a difference in extension-specific or kit-specific logic, params, roles, APIs, or tests.

Summary

Ranked by impact for parity work:

1. Kit queryOnWrite self-retrigger loop — no status/idempotency guard, where the extension had one. Cost and correctness (§7).
2. Multimodal unimplemented in the kit, while still an offered EMBEDDING_PROVIDER value (§3).
3. Re-embed-on-update semantics flipped — the extension never re-embeds a terminal document; the kit does (§6).
4. Status field shape change breaks any consumer reading status.<instanceId>.state (§6).
5. Backfill de-batched — per-document tasks and per-document embedding calls, plus the loss of the metadata-doc gate, mean every redeploy re-embeds the whole collection (§9).
6. Vector-store error codes collapsed to unknown (§8).
7. OpenAI embeddings model changed (ada-002 → 3-small@512), which is not backwards compatible with existing indexes (§1, §2).

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Embedding dimensions	Two dimension tables that disagree with each other — one for the Firestore index, one for actual client output	One table, dimensionFor(), used for both index and client	Index/embedding mismatch upstream. The extension creates a 512-dim vector index for multimodal and openai while writing 1408/1536-dim vectors, so the index is unusable. The kit is internally consistent. See the dimension matrix below.
2	OpenAI client	text-embedding-ada-002, default 1536 dimensions, batchSize 16	text-embedding-3-small, explicit 512, batchSize 1	Breaking for existing installs. Existing extension openai deployments migrating to the kit get entirely different embeddings. See 2a–2b.
2a	Missing key	Client built with an undefined key, fails at API call	Throws "OpenAI embeddings require OPENAI_API_KEY" at construct	Kit fails earlier.
2b	Errors	Caught → "Error with embedding, see function logs for details"	Raw OpenAI error propagates	Different error surface.
3	Multimodal	Implemented: downloads the image from config.bucketName, base64-encodes it, POSTs to the multimodalembedding@001 predict endpoint — that endpoint path hardcodes us-central-1, a typo, so it is broken	MultimodalEmbedClient throws "Multimodal embeddings are not implemented in this package"	Functional dead-end in the kit, yet multimodal is still an accepted EMBEDDING_PROVIDER value, and the kit still declares storage-component.googleapis.com and roles/storage.objectAdmin.
4	Custom endpoint	Constructed top-level at module load	Constructed per-invocation	See 4a–4e.
4a	Construct-time failure	Cold-start crash of all functions if endpoint/batchSize/dimension unset	Error scoped to one call	Kit contains the blast radius.
4b	batchSize	Required, from param	customEmbeddingsBatchSize ?? 1, then throws if unset	—
4c	Content-type check	Rejects a non-JSON response	No check	Kit regression.
4d	Bad schema	"...response does not match expected schema"	Raw zod error	Less readable in the kit.
4e	Length mismatch	"...response does not contain embeddings"	"...response does not contain embeddings for all inputs"	Text differs only.
5	Genkit (gemini/vertex)	Hardcodes outputDimensionality: 768; no truncation; config.location (the LOCATION param, always set); overrides getSingleEmbedding with client.embed()	Passes config.dimension; truncates the returned embedding to config.dimension; config.region ? {location} : {}, falling back to the Genkit default when FUNCTION_REGION is absent; inherits embedMany([input])[0]	Region can differ from the deployment region in the kit.
6	Status field	Nested per-process via @invertase/firebase-extension-utilities: status.<EXT_INSTANCE_ID> = { state, startTime, updateTime, completeTime, createTime }, status.textQuery = { … }. States PROCESSING | COMPLETED | ERROR | BACKFILLED | FAILED_BACKFILL. Two writes per document	Flat: status = { state: "COMPLETED" } or { state: "ERROR", message }. Single write. No PROCESSING, no timestamps, no BACKFILLED / FAILED_BACKFILL	Different idempotency. See 6a–6b.
6a	Re-embedding on update	Never re-embeds once state is terminal — the processor skips PROCESSING/COMPLETED/ERROR/BACKFILLED. Editing input after a successful embed does nothing	Re-embeds when input changes — guard is beforeInput === input && output exists → return	Materially different behaviour on document updates.
6b	ERROR retry	Never retries	Retries ERROR documents on every subsequent write	—
7	queryOnWrite	Runs the query as a FirestoreOnWriteProcess with id: 'textQuery'; once status.textQuery.state is terminal, later writes are skipped	handleQueryOnWrite has no status guard and no dedupe — writes {result} back to the same document with merge: true, which re-fires onDocumentWritten, whose data.query is still a string, so it queries and writes again	Self-sustaining trigger loop, billed per iteration (one embedding call plus one vector query each pass). See 7a–7c.
7a	limit validation	Passes the raw document limit field straight to findNearest — no parseLimit on the onWrite path, so a string "5" errors	Calls parseLimit	Kit fixes an upstream bug.
7b	prefilters	Zod-parses on the onWrite path	Casts data.prefilters as Prefilter[] unvalidated	Kit regression. The callable path is validated on both sides.
7c	Error handling	errorFn: console.error marks status ERROR and the function succeeds	Lets the error throw out of the handler	—
8	Vector-store error mapping	FirestoreVectorStoreClient.toHttpsError maps FirebaseFirestoreError code firestore/<code> → the matching HttpsError code (15-code allowlist), else unknown with a {firestoreCode} detail; messages containing opstr → invalid-argument with "Invalid operator in query: <operator> for <field>" (per-prefilter context); findNearest failures wrapped separately	Rethrow if already an HttpsError, otherwise new HttpsError("unknown", err.message)	Regression. Callable clients lose invalid-argument / permission-denied / not-found discrimination and the per-prefilter context.
9	Backfill / update	Chunked, gated, resumable	Per-document, ungated	See 9a–9g. UPDATE_ON_CONFIGURE is declared in extension.yaml but never read by extension code — the extension's update path gates on DO_BACKFILL instead. The kit actually reads updateOnConfigure.
9a	Enumerate	collection.listDocuments()	collection().get() — loads every document into memory	Kit regression at scale.
9b	Enqueue	taskThreadTrigger, chunks of 50 ids per task, task-thread doc for progress	One task per document	—
9c	Embedding	batchEmbedFn → getEmbeddings(batch) at the client batchSize	getSingleEmbedding per document, one API call per document	Kit regression at scale.
9d	Gating	Metadata doc at _<instanceId>/index compares embeddingProvider / dimension / inputField / outputField and skips when unchanged; runtime.setProcessingState('PROCESSING_WARNING', …) when backfill is disabled	No metadata doc, no gating, no processing state — always re-embeds every document	Kit regression.
9e	Skip rules	shouldBackfill (input is a string) plus skipping documents whose existing state is not BACKFILLED	Task skips when input is not a string; the update task additionally requires an existing output field	—
9f	Write	Batched writer.commit() per chunk, BACKFILLED / FAILED_BACKFILL	Per-document set(merge) with state: "COMPLETED"	—
9g	Failure	Caught, document marked failed, task succeeds	Throws → task retries	—
10	Lifecycle wiring	onInstall → backfillTrigger (createIndex, then backfill), onConfigure → updateTrigger (createIndex, then update). Index creation failure surfaces as "Error creating firestore Vector index" / "…during update"	afterFirstDeploy and afterRedeploy both enqueue one initVectorSearch task → createIndex, then enqueue backfill if doBackfill and update if updateOnConfigure	First deploy can also run the update pass, and every redeploy can also run the full backfill — the extension keeps those install-only and configure-only respectively. The kit also has no error wrapping around createIndex.
12	createIndex logging	Logs the whole result JSON	Logs {operationName}	—
14	logs.init()	Runs at module load and always prints <omitted> for both keys	Runs lazily on first context build and prints <omitted> only when the key is actually set	The kit's log now reveals which keys are configured.
15	Public library surface	None	lib.ts / the ./lib export — handlers, the config resolver, the clients, and createIndex are all exported for embedding in a user codebase	Kit-only.
16	Install metadata	extension.yaml, PREINSTALL.md, POSTINSTALL.md, icon.png	None — IAM and params are documented in README.md instead	Kit-only difference.

Embedding dimensions

Provider	ext config.getDimension() (used for Firestore index)	ext client actual output	kit dimensionFor() (index + client)
gemini	768	768	768
vertex	768	768	768
multimodal	512	1408	1408
openai	512	1536 (ada-002)	512 (dimensions: 512)
custom	param	param	param

Params

Param	Extension	Kit
LOCATION	select, 20 regions, required, immutable; drives task queues and the Vertex location	Absent — uses process.env.FUNCTION_REGION; queuePath() throws "FUNCTION_REGION is required to resolve task queues." when unset
COLLECTION_NAME	Default products in the yaml — but config.ts falls back to 'embeddings', contradicting it	Default products everywhere, so the programmatic default changed
DO_BACKFILL	select true/false, required: true, no default	defineBoolean, no default — the CLI prompts, matching the extension. A programmatic caller omitting it gets ?? false
UPDATE_ON_CONFIGURE	select, required — unused by code	defineBoolean, used
CUSTOM_EMBEDDINGS_BATCH_SIZE / _DIMENSION	string, parseInt	defineString default "" → optionalNumber (Number(v) > 0, so 0 and NaN become undefined)
CUSTOM_EMBEDDINGS_ENDPOINT	string	Same, "" → undefined
BUCKET_NAME	Read from env, not declared in yaml; fallback ${PROJECT_ID}.appspot.com	storageBucket param, same fallback
INSTANCE_ID, UPDATE_TRIGGER_QUEUE_NAME, UPDATE_TASK_QUEUE_NAME, BACKFILL_TRIGGER_QUEUE_NAME, BACKFILL_TASK_QUEUE_NAME	—	Kit-only, default kit-${INSTANCE_ID}-<name>

Queue paths: ext locations/${LOCATION}/functions/backfillTask; kit
locations/${region}/functions/kit-${instanceId}-backfillTask.

Roles and APIs

Role	Extension	Kit
cloudtasks.enqueuer	✗	✓
iam.serviceAccountUser	✗	✓

Kit reworded the API reason strings and still says "uses Vertex AI for embedding and vector search when configured".

Events

• Ext publishes none. There is no eventarc code anywhere in
  functions/src, so the declared events never fire.
• Kit publishes all four, but only from handleEmbedOnWrite. onSuccess
  carries subject: <doc path> and data: {outputFieldName}; onError carries
  {message}. No events are published from the query, backfill, update, or init
  paths.

The extension's onSuccess description is also wrong — copy-pasted from
storage-resize-images ("Occurs when image resizing completes successfully").
The kit ships no yaml, so this does not transfer.

Deploy and resources

	ext	kit
embedOnWrite / queryOnWrite	512MB, 540s	512MiB, 540s, plus secrets
queryCallable	512MB, no timeout set	512MiB, plus secrets
—	—	kit-only initVectorSearch task function

The extension declares no secret bindings on its trigger/task functions (the
extension runtime injects them); the kit binds GEMINI_API_KEY /
OPENAI_API_KEY on every function.

[CorieW]

Kit: rtdb-limit-child-nodes

Parity analysis: rtdb-limit-child-nodes

Kit: kits/rtdb-limit-child-nodes
Upstream extension: rtdb-limit-child-nodes
Out of scope: Kits-vs-Extensions API differences, and v1 → v2 function upgrades. Everything below is extension-specific or kit-specific logic, params, roles, APIs, or testing.

Summary

• Migration note — NODE_PATH renamed. An old extension .env carries the key NODE_PATH, which the kit does not read. The CLI prompts for RTDB_NODE_PATH instead.
• Fix — MAX_COUNT = 0 is rejected. The extension's ^\d+$ regex accepted 0, deleting all children on every write.
• Fix — invalid config now fails loudly. An absent MAX_COUNT gave the extension NaN, which silently logged pathSkipped on every event. Only reachable outside a normal install, since the param is required: true behind ^\d+$ — a hand-edited .env, a stale deploy, or the emulator.
• Region. The kit sets none, so it always deploys to us-central1; the extension picked up the install LOCATION.
• Testing improved — the extension has zero tests; the kit ships three vitest suites.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Config resolution timing	Resolves at module load and never validates. An absent MAX_COUNT becomes Number(undefined) = NaN, so numChildren() > NaN is always false and every event silently logs pathSkipped. An empty MAX_COUNT= gives Number("") = 0 instead, which deletes every child on every write	Resolves lazily in getConfig() on first event and throws outside the handleChildCreated try/catch	Kit fixes silent misbehaviour. The invocation now fails loudly instead of skipping everything or mass-deleting.
2	logs.init()	Fires at module load on every cold start	Fires once inside getConfig()	Never runs if the function is never invoked.
3	Admin app	Never calls initializeApp()	Calls initializeApp() in src/index.ts	—
4	Null guards	Unguarded — updates[child.key] on a null key writes the literal key "null"	Returns cleanly when event.data or parent is missing, and skips children whose key is null	Kit fixes an upstream bug.
5	Trigger ref	extension.yaml uses .../refs/${param:NODE_PATH}/{messageid}; its code's functions.database.ref(config.databaseInstance) passes the instance as the ref — inert for extension deploy, wrong for emulator/standalone	Builds <trimmedPath>/{nodeId}	Wildcard renamed, and the kit slash-trims the path, so /rooms/messages/ and rooms/messages are equivalent — the extension treats them as distinct refs.
6	Deploy vs runtime ref	No equivalent	Branches on FUNCTIONS_CONTROL_API === "true", emitting {{ params.RTDB_NODE_PATH }}/{nodeId} CEL during CLI discovery and the concrete path at runtime	Kit-only.

Params

Param	Extension	Kit
NODE_PATH → RTDB_NODE_PATH	NODE_PATH, required with no default, validationRegex ^\S+$ rejecting spaces	Renamed to RTDB_NODE_PATH, because Node.js reserves NODE_PATH for module resolution. Also required with no default, same validation. Trims leading/trailing / and rejects empty after trim
MAX_COUNT	string + validationRegex ^\d+$, required with no default. 0 passes the regex, so it deletes all children on every write	defineInt, required with no default, same regex — but resolveRtdbLimitConfig throws on non-positive values, so 0 fails at runtime instead of mass-deleting
SELECTED_DATABASE_INSTANCE	Default ${DATABASE_INSTANCE} system param, validationRegex ^([0-9a-z_.-]*)$	Same validation. Default derived from the FIREBASE_CONFIG.databaseURL hostname; if absent or unparseable there is no default and the CLI prompts
LOCATION	Read into the config object — unused, but logged	Absent

Migration note

NODE_PATH was renamed to RTDB_NODE_PATH, so an old extension .env does not
carry the value over. Both RTDB_NODE_PATH and MAX_COUNT are required with no
default, matching the extension, so an incomplete .env prompts at deploy
rather than falling back to a kit default.

Roles and APIs

Extension declares billingRequired: true; kit declares no billing flag. Kit README warns that setting a custom runtime service account breaks the CLI's automatic role setup.

Deploy and resources

Region. The extension picks up the LOCATION system param at install time. The kit sets no region — always the default us-central1. tests/deploy-options.test.ts asserts this explicitly.

[CorieW]

Kit: speech-to-text

Parity analysis: speech-to-text

Kit: kits/speech-to-text
Upstream extension: speech-to-text (v0.1.9)
Out of scope: Kits-vs-Extensions API differences (params SDK instead of extension.yaml, .env instead of install prompts) and the v1 → v2 functions upgrade, except where they change observable behaviour.

Summary

• Migration break — transcoded .wav lands in a different Storage location. The extension derived the destination from the local /tmp path; the kit derives it from the object name (§1).
• Fix — timeout raised to 540s. The extension took the 60s v1 default while polling longRunningRecognize in-process (§2).
• Fix — /tmp files are cleaned up. The extension never unlinked them, so a busy instance fills its tmpfs (§3).
• Fix — empty alternatives no longer crashes, producing a typed NULL_TRANSCRIPTION failure instead of a generic error (§4).
• Validation regex dropped for EXTENSION_BUCKET — its BUCKET_PICKER input cannot also carry a regex.
• Region. The kit sets none, so the function deploys to the CLI/codebase default rather than the install LOCATION.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	Transcoded .wav output path	Derives the Storage destination from the local /tmp path	Derives it from the object name, and normalises the prefix separator	Behaviour change. The transcoded audio lands in a different Storage location than it did under the extension. See the path matrix below.
1a	Transcript .txt path	transcribeAndUpload builds its output URI with name.replace("tmp/", ""), which cancels the extension's spurious tmp/ segment	Retains that replace("tmp/", "") even though it no longer has anything to undo	Unaffected in the common case. For an input named tmp/a.mp3 the extension writes tmp/a.mp3.wav_transcription.txt and the kit writes a.mp3.wav_transcription.txt — both wrong, wrong in different ways.
2	Function timeout	No timeoutSeconds declared, so the function takes the v1 default of 60 seconds. longRunningRecognize is polled to completion in-process	Defaults timeoutSeconds to 540 (src/export-config.ts), and exposes it as an overridable config field	The extension kills any audio needing more than a minute of recognition. Memory matches (availableMemoryMb: 1024 / "1GiB").
3	Temp file cleanup	Never removes the files it writes under /tmp. Because /tmp is tmpfs shared across warm invocations, a busy instance fills its disk (ENOSPC/OOM)	Unlinks both the downloaded copy and the transcoded output in a finally block, tolerating files that were never created	Kit fixes a resource leak.
4	Empty alternatives array	getTaggedTranscriptionOrNull reads result?.alternatives?.[0].transcript. When the Speech API returns a result with an empty alternatives array, that throws a TypeError, which escapes to the handler's outer catch and is reported as a generic error event	result?.alternatives?.[0]?.transcript, so the same input produces a clean NULL_TRANSCRIPTION failure and a typed fail event	Kit fixes an upstream crash.
4a	isNullFreeList	Tests item !== null, which lets undefined entries through	item != null	Kit fixes the same class of bug.
5	sampleRateHertz type	Passes streams[0].sample_rate from ffprobe straight into the recognition config. ffprobe reports it as a string at runtime despite the FfprobeData typings, so a string is sent where the API expects a number	Wraps it in Number(...)	Kit fixes an upstream type bug.
6	Initialisation timing	admin.initializeApp(), Eventarc channel setup, SpeechClient construction and logs.init() at module load	All of it lazily on the first invocation via getContext()	Observable only in when the Initializing extension with configuration log line appears. The kit's logged config also includes the resolved timeoutSeconds and memory.

Transcoded .wav output path

Extension:

storagePath: config.outputStoragePath
  ? `${config.outputStoragePath}${transcodeResult.outputPath}` // "transcriptions" + "/tmp/a.mp3.wav"
  : transcodeResult.outputPath.slice(1);                       // "tmp/a.mp3.wav"

Kit:

const transcodedObjectName = `${filePath}.wav`;
storagePath: config.outputStoragePath
  ? `${config.outputStoragePath.replace(/\/$/, "")}/${transcodedObjectName}`
  : transcodedObjectName;

For an input object named a.mp3:

OUTPUT_STORAGE_PATH	Extension writes	Kit writes
unset	tmp/a.mp3.wav	a.mp3.wav
transcriptions	transcriptions/tmp/a.mp3.wav	transcriptions/a.mp3.wav
transcriptions/	transcriptions//tmp/a.mp3.wav (double slash)	transcriptions/a.mp3.wav

Params

Param	Extension	Kit
LOCATION	select over 8 regions, default us-central1, immutable	Absent — the kit sets no region, so the function deploys to the CLI/codebase default
EXTENSION_BUCKET	selectResource, validationRegex: ^([0-9a-z_.-]*)$, default ${STORAGE_BUCKET}	defineString with BUCKET_PICKER, default storageBucket, no regex — the picker input cannot also carry one
timeoutSeconds, memory	Not configurable	Kit-only config fields, for library consumers

Events

The event payloads differ for an unexpected thrown error. The extension publishes
data: { error } with the raw Error instance; message and stack are
non-enumerable, so subscribers receive {"error":{}}. The kit publishes
data: { error: { message, stack } }.

The kit's error event, like the extension's, omits objectName.

Deploy and resources

• Timeout: extension 60s (v1 default), kit 540s — see §2.
• Region: extension LOCATION param (8-region select, immutable); kit sets none.

[CorieW]

Kit: storage-resize-images

Parity analysis: storage-resize-images

Kit: kits/storage-resize-images
Upstream extension: storage-resize-images
Out of scope: Kits-vs-Extensions API surface differences, and v1 → v2 function upgrades. Everything below is extension-specific or kit-specific logic, params, roles, APIs, or testing.

Summary

• Config default flips. deleteOriginal unset falls to onSuccess in the extension but never in the kit; isAnimated unset is false in the extension and true in the kit.
• Partial-environment hazard. Because firebase-functions/params defaults are deploy-time only, unset IMAGE_TYPE / SHARP_OPTIONS throw at runtime in the kit where the extension yielded undefined / "{}".
• Deletion risk. An empty imageTypes list yields zero outputs, the run counts as success, and the original is deleted under on_success.
• Validation regex dropped for IMG_BUCKET — its BUCKET_PICKER input cannot also carry a regex.
• Backfill deleted entirely — the extension keeps it commented out but intact.

Runtime behaviour

#	Area	Extension	Kit	Impact
1	deleteOriginal unset	Falls to default: → onSuccess (src/config.ts:28-37)	undefined → never (src/export-config.ts:122-136)	Originals are no longer deleted by default.
2	isAnimated unset	allowAnimated returns false (x === "true" || undefined ? true : false) (src/config.ts:42-49)	Defaults true (src/export-config.ts:138-144)	Animated images are now resized by default.
3	IMG_SIZES unset	.split(",") on undefined → TypeError at module load (src/config.ts:76)	?? [] → no resize tasks, silent no-op (src/export-config.ts:175)	Extension crashes loudly; the kit does nothing quietly.
4	BLOCK_NONE filter level	Not in map → throws Invalid HarmBlockThreshold (src/config.ts:52-58)	Mapped → passes through (src/export-config.ts:92-98)	Kit accepts a value the extension rejects.
5	Region source	process.env.LOCATION, fallback "us-central1" (src/content-filter.ts:137)	process.env.FUNCTION_REGION, throws if absent (src/content-filter.ts:81-83)	Kit fails instead of silently defaulting.
6	imageTypes empty list	[""] → bad content-type lookup	[] → zero outputs, run counts as success	Data loss risk. Under on_success the original is deleted with nothing produced.
7	cacheControlHeader: ""	Truthy check → falls back to the original's value	?? → sets literal "" (src/resize-image.ts:200-201)	Cache header differs for an empty param.
8	Resized marker	metadata.resizedImage = true (boolean)	= "true" (string)	Same on the GCS wire; differs for direct-call consumers.
9	Init / lifecycle	initializeApp(), setupEventChannel(), and logs.init(config) all run at module load, unconditionally	Lazy getContext() on the first event; guards admin.apps.length === 0 (src/index.ts:61-79)	Config is never logged if the function never fires.
10	recordErrorEvent	Not awaited (src/index.ts:177)	Awaited, and wraps non-Error throws	Kit fixes a dropped-promise bug.
11	Backfill	Kept commented out but intact: the backfillResizedImages resource, DO_BACKFILL, BACKFILL_BATCH_SIZE, lifecycleEvents, plus live imports of getFunctions / getExtensions and convertToObjectMetadata	Deleted entirely — no backfill code, no lifecycle hooks, backfill log helpers gone	The kit cannot backfill.

Params

Param	Extension	Kit
IMG_BUCKET	selectResource + regex ^([0-9a-z_.-]*)$	BUCKET_PICKER, no regex — the picker input cannot also carry one
INCLUDE_PATH_LIST / EXCLUDE_PATH_LIST	Install-time regex only	The only params with runtime validation: validatePathListsFromEnv() runs at module load and throws on cold start (src/config.ts:124-127). The kit regex also permits an empty string
DELETE_ORIGINAL_FILE	String only	Accepts deleteOriginal as boolean or string
IMAGE_TYPE	Parses jpeg,webp	defineList requires ["jpeg","webp"] — format change

Param runtime contract

The kit reads params through firebase-functions/params, where a declared
default: is a deploy-time value — the CLI writes it into the deployed
.env, and at runtime .value() only reads process.env. Against a partial
environment the kit therefore differs from the extension's direct
process.env reads:

Env var	Extension (unset)	Kit (unset)
IMAGE_TYPE	undefined	throws SyntaxError — ListParam JSON-parses the raw var
IS_ANIMATED / REGENERATE_TOKEN	false / false	false / false, i.e. not the declared true defaults (the config-object path above still defaults them to true)
FUNCTION_MEMORY	n/a (extension.yaml)	0 → normalizeMemory("0") returns an invalid MemoryOption
SHARP_OPTIONS	"{}" via ||	"" → JSON.parse("") throws in allowAnimated