cross-language-safety
Skill1 starsChanged 28 days agoBSD-3-ClauseView on GitHub
Prevents cross-language type mismatches in full-stack apps (Dart/Flutter ↔ JSON ↔ PostgreSQL/PostgREST/Deno). Use when building or auditing APIs, DTOs, sync engines, or any server↔client data flow. Also use when setting up observability (logging, Sentry, analytics) for API communication layers.
In this repository52 other files it gives its agents.
- academic-research-assistantSkill
- answer-sheetSkill
- app-graphicsSkill
- app-landing-pageSkill
- app-screenshotsSkill
- break-uiSkill
- consumer-app-from-behaviorSkill
- dart-tool-scriptsSkill
- decision-sweepSkill
- engineering-diarySkill
- figma-review-loopSkill
- flutter-app-size-auditSkill
- flutter-async-at-the-edgeSkill
- flutter-async-cubit-safetySkill
- flutter-bloc-clean-architectureSkill
- flutter-clean-architecture-tddSkill
- flutter-cubit-smart-cachingSkill
- flutter-error-logging-conventionsSkill
- flutter-observability-instrumentationSkill
- flutter-paywall-and-review-timingSkill
- flutter-precommit-cleanupSkill
- flutter-router-decisionSkill
- flutter-runtime-safetySkill
- flutter-shorebird-otaSkill
- flutter-stream-architectureSkill
- flutter-strict-analysisSkill
- flutter-web-first-paintSkill
- forced-pivot-15-daySkill
- gplay-consoleSkill
- ios-distribution-feature-flagsSkill
- launch-readinessSkill
- launch-watchSkill
- locale-expert-reviewSkill
- market-pulseSkill
- mobile-ui-referenceSkill
- moscow-prioritizationSkill
- orchestrate-agentic-engineeringSkill
- parallel-agent-inboxSkill
- paywall-conversion-flowSkill
- paywall-transparencySkill
- proactive-crash-repair-loopSkill
- promise-auditSkill
- pr-preview-shippingSkill
- ship-first-dollar-appSkill
- slim-ios-simulator-fleetSkill
- spec-sql-harnessSkill
- store-launch-mastermindSkill
- sync-contextSkill
- task-blitzSkill
- techdebtSkill
- vendor-decisionSkill
- web-interface-reviewSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 40
Never use
as Typeon server data: Always use safe parsers: - Distinctive: line 61
Add transaction tracing for API calls (request and response parsing as spans)
- Distinctive: line 72
When auditing an existing codebase, see references/audit-checklist.md
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cross-Language Type Safety
The Problem
PostgreSQL, PostgREST, Deno, and Dart each serialize types differently:
bigint-> deno-postgres returns a JSbigint, whichJSON.stringifycannot serialize.bigint-> PostgREST returns a JSON number, which loses precision past 2^53 in JS and on Flutter web.numeric-> deno-postgres returns a string.numeric-> PostgREST returns a JSON number, which Dart decodes asintwhen it has no fractional digits.boolean→ some drivers return0/1timestamp→ format varies by driver configjsonb→ may be string or parsed object
Dart's as int? throws TypeError on strings. These bugs are silent — no server error, no 4xx/5xx, just a client-side crash.
Rules
Server Side (API)
- Explicitly cast all types before JSON response. Wrap every numeric DB field with
Number()in Deno/JS. Never trust the driver's default serialization. - Structured JSON logging on every endpoint:
- Request: method, path, user_id (from JWT), duration_ms, status_code
- Error: full stack trace, sanitized request body (no tokens/passwords), user context
- Propagate
X-Request-IDheader through the chain
- Health endpoint:
GET /healththat checks DB connection, returns service versions.
Client Side (Flutter/Dart)
Never use
as Typeon server data. Always use safe parsers:// BAD final version = json['version'] as int?; // GOOD final version = SafeJson.parseInt(json['version']);- Build a
SafeJsonutility class:parseInt(dynamic)— handles int, string, double, nullparseDouble(dynamic)— handles double, string, int, nullparseString(dynamic)— handles string, num, nullparseBool(dynamic)— handles bool, int, string, nullparseDateTime(dynamic)— handles ISO string, int (epoch), null
- Every DTO/model
fromJsonmust use SafeJson, never raw casts. - Sentry integration for API layer:
- Capture all deserialization failures with full context (endpoint, raw response, expected type)
- Add transaction tracing for API calls (request and response parsing as spans)
- Log type coercions as breadcrumbs (when SafeJson converts string→int, etc.)
- PostHog events: Track API call success/failure with timing, auth refresh events.
PostgREST Specifics
- Know PostgREST type mappings: See references/postgrest-types.md
Audit Checklist
When auditing an existing codebase, see references/audit-checklist.md
For Sub-Agents
Include this in every Flutter task prompt that touches API code:
"Use SafeJson for all server response parsing. Never use
as Typeon JSON data. Log deserialization anomalies to Sentry."
Sources
- https://docs.postgrest.org/en/stable/references/api/tables_views.html
- https://www.postgresql.org/docs/current/functions-json.html
- https://github.com/denodrivers/postgres/blob/main/query/decode.ts
- https://dart.dev/resources/language/number-representation
- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

