This document maps Tessera’s design and implementation decisions to the SAFE Guide v2026.1 principles required for Built for NetSuite (BFN) certification. It is intended for SDN technical reviewers, NetSuite administrators, and technical evaluators performing due diligence.
References: SAFE Guide v2026.1 · SuiteCloud Developer Network
| Area | Status |
|---|---|
| SuiteScript version | SuiteScript 2.1 throughout — no 1.0 patterns |
| Deployment method | SDF (SuiteCloud Development Framework) |
| API usage | Published SuiteCloud APIs only |
| Restricted APIs | None used |
| External dependencies (runtime) | None |
| External service calls (runtime) | None (AI narration via N/llm routes through OCI — planned v1 feature) |
| SuiteCloud Plus required | No |
| Third-party libraries | Apache 2.0 and MIT licensed only |
| Automated testing | Yes — @oracle/suitecloud-unit-testing (Jest) |
| BFN badge target | BFN — AI Application (due to planned N/llm use) |
The following table lists every SuiteScript module used or planned in Tessera. The distinction between current and planned reflects the state of the production codebase — both categories use only published SuiteCloud APIs.
| Module | Status | Purpose |
|---|---|---|
N/query |
Current | SuiteQL execution for metric computation |
N/record |
Current | Custom record read/write (MDL, CRL, Benchmark records) |
N/log |
Current | Audit and error logging |
N/file |
Current | Static asset loading from File Cabinet |
N/runtime |
Current | Script execution context, current user |
N/url |
Current | Suitelet and record URL resolution |
N/search |
Planned | Saved Search execution for permission-scoped query paths |
N/task |
Planned | CRL Map/Reduce task scheduling |
N/currentRecord |
Planned | Client-side script current record context |
N/llm |
Planned | AI narration (variance explanation, anomaly flagging) |
N/cache |
Planned | Open-period metric result caching |
No restricted APIs are used. No undocumented internal namespaces. No DOM manipulation outside Tessera’s own Suitelet-rendered pages.
Tessera’s architecture is built on a thorough understanding of the NetSuite data model and platform constraints established through active platform validation against a live NetSuite 26.1 sandbox. Validated findings include:
accountPeriodActivity as the correct table for running balance (point-in-time GL balance) computationtransactionLine field names, boolean syntax, and line filter requirementstl.subsidiary, not t.subsidiary)TransactionAccountingLine as the correct table name for accounting line accesstransaction.type does not require BUILTIN.CF() wrapping in WHERE clausesQuery Templates 1–4 are fully designed and validated. Template 5 (Paired Query Comparator for cohort metrics) is designed and stubbed for v2 implementation.
Tessera’s architecture is explicitly designed around governance constraints:
CQRS as the governance solution. Dashboard portlets read pre-computed Metric Result records (R6) — they never execute live queries at render time. The entire computation cost is borne by scheduled Map/Reduce scripts (10,000 governance units per execution), which have the highest allotment of any script type. Suitelets and portlets — which have the lowest allotment (1,000 units) — perform only record reads and rendering.
Scheduled computation. The Computed Result Layer (CRL) runs as Map/Reduce scripts. Metric computation is decoupled from user-facing script execution. No metric computation happens inside a User Event script or Suitelet.
Context guards on User Event scripts. User Event scripts used for CRL cache invalidation include context.type guards to prevent execution during bulk CSV imports and web service operations, avoiding governance flooding.
Closed-period immutability. Metric Results for closed accounting periods are computed once and stored permanently. They are never recomputed unless explicitly requested by an administrator. This bounds the computational load to open periods only.
Static assets from File Cabinet. All JavaScript bundles (ECharts, math.js, AG Grid), CSS, and fonts are served from NetSuite File Cabinet. No CDN requests, no external asset loading at runtime. Assets load within the NetSuite infrastructure and are subject to File Cabinet performance characteristics already understood by the platform.
Pre-computed read model. Portlets read a single Metric Result record per metric per period — no query fan-out at render time. The read cost is O(n metrics visible to this user), not O(all transactions in the account).
Benchmark data as static records. Industry benchmark datasets are stored as custom records (Benchmark Series R13, Benchmark Data Point R14). They are not fetched from external services at render time.
N/llm governance awareness. The planned AI narration layer uses N/llm. Tessera will implement the governance usage checks (llm.getRemainingFreeUsage()) required by the SAFE Guide and degrade gracefully when the monthly free-usage pool is exhausted.
Stable internal ID prefix. All Tessera custom record types, scripts, deployments, and fields use the tessera_ prefix for internal IDs. Custom record internal IDs use custrecord_tess_ and custrecord_tqc_. These prefixes will not collide with customer customizations or other SuiteApps using the custrecord_ namespace.
No shared mutable state. Tessera does not modify standard NetSuite records. All data is stored in Tessera-owned custom records. Tessera does not read or write customer customization records.
User Event context guards. User Event scripts include context.type checks to prevent execution in contexts where they would interfere with other processes (CSV imports, web services, mass updates).
SuiteCloud Plus not required. Tessera does not use APIs or features that require the SuiteCloud Plus governance upgrade. It is compatible with standard NetSuite governance limits.
Authentication. Tessera uses NetSuite’s existing session authentication exclusively. There is no Tessera-specific login, no separate credential store, and no additional authentication surface.
Authorization — five-role model. Tessera’s role capability model maps NetSuite roles to five named capabilities: define metrics, approve metrics, view all metrics, configure dashboards, administer the system. Role assignments are enforced using NetSuite’s native role and permission system.
Portlet execution as current user. Portlet scripts run in the context of the logged-in user. NetSuite’s native record-level permissions are enforced at query time. A user who cannot see a transaction through standard NetSuite access cannot see that transaction contribute to a Tessera metric.
Data residency. All Tessera data — metric definitions, computed results, benchmark datasets — resides within the NetSuite account. Nothing is transmitted to external services during normal operation (see AI narration note below).
AI narration — OCI routing. The planned N/llm AI narration feature routes through Oracle Cloud Infrastructure (OCI) Generative AI services via NetSuite’s native module. This is Oracle’s published infrastructure for N/llm. Tessera will implement the input sanitization, output validation, and access controls required by SAFE Guide Section 14.8.12.
License activation — offline HMAC. License keys are validated using offline HMAC verification against a per-account key stored in the Tessera Account Configuration record. No license server call is made during normal operation.
No sensitive data in custom fields. OCI credentials and any sensitive configuration values are stored using NetSuite’s API Secrets Management, not in plain-text custom record fields.
Privacy. Tessera does not collect, transmit, or process personal data beyond what is inherent in the NetSuite records it reads as part of metric computation (e.g., transaction records may contain contact names). Tessera does not create new personal data records or expose personal data through its UI beyond what the user already has permission to see in NetSuite.
Unit testing framework. Tessera uses @oracle/suitecloud-unit-testing — Oracle’s published Jest-based SuiteScript testing framework — with full NS module mocking.
Slot resolver test suite. The Query Layer slot resolver — the module responsible for translating Metric Definitions into executable SuiteQL statements — has 79 unit tests covering all template types, multi-tier routing, period resolution, constant components, sign convention, and duplicate account detection. These tests run against Node.js with SuiteScript shims; no NetSuite sandbox access is required.
Continuous integration. GitHub Actions runs TypeScript compilation and the full test suite on every commit.
Platform validation. Key architectural assumptions were validated against a live NetSuite 26.1 sandbox before the query engine was implemented. Validation findings are documented and informed the Query Template designs.
Sandbox-first deployment. All Tessera releases are deployed to a sandbox account for validation before production deployment.
Tessera is distributed as a Managed SuiteApp via the SuiteApp Marketplace. The SuiteApp definition in SuiteApp Control Center is created as Managed — this decision is irreversible and was made before the definition was created.
Managed SuiteApp implications:
PUBLISHERPREF: PROTECTED is set in suiteapp.config.xmlhiding.xml and locking.xml are included in suiteapp/src/InstallationPreferences/ to enforce install-time access controlsSDF version-controlled deployment. Every NetSuite object Tessera creates is defined as SDF XML and managed in the product Git repository. Releases are tagged and correspond to SDF bundle versions.
Baseline library immutability. Tessera’s baseline Metric Registry records (is_baseline: true) are system-enforced read-only via User Event scripts. Customers cannot modify baseline definitions; they can only deactivate them or create governed forks. This ensures Tessera can update baseline definitions in future versions without conflicting with customer data.
Upgrade path. Product upgrades are delivered as new SDF bundle versions. Customer metric definitions, stored in custom records, are not affected by product upgrades. Metric Result records from prior versions are preserved.
Sandbox account support. Tessera’s license activation design includes PROD/SBX environment type separation, allowing customers to install Tessera in sandbox accounts without consuming production license terms.
N/llmAll third-party libraries are verified to carry permissive licenses compatible with commercial SuiteApp distribution.
| Library | Version | License | Purpose |
|---|---|---|---|
| Apache ECharts | 5.x | Apache 2.0 | Chart rendering |
| AG Grid Community Edition | Current | MIT | Tabular data display |
| math.js | 12.x | Apache 2.0 | Statistical and formula evaluation |
THIRD_PARTY_LICENSES.md is maintained in the product repository listing all dependencies and their licenses, including transitive dependencies. No GPL, AGPL, or LGPL licensed code is included.
Tessera’s development process references OWASP security principles. Relevant controls:
Tessera plans to use N/llm for AI-powered metric narration. This triggers the BFN — AI Application badge requirement.
| SAFE 14 Requirement | Tessera Status |
|---|---|
| AI policy document | Drafted — docs/20_founding/tessera_ai_policy.md |
| AI risk assessment | Included in AI policy document |
| AI asset inventory | N/llm for narration; scoped to metric context |
| EULA AI terms (Oracle AI Terms reference) | Included in click-through EULA |
| Input sanitization | Prompts constructed from MDL-structured context only; no free-form user input passed to model |
| Output validation | Narration outputs reviewed before storage; no raw LLM output written to financial records |
| Access controls | AI narration restricted to roles with metric view permission |
| Usage governance | llm.getRemainingFreeUsage() checked before invocation; graceful degradation when pool exhausted |
| Prompt injection controls | System prompts constructed server-side from typed DTOs; no user-controlled prompt injection surface |
| Human-in-the-loop | AI narration is advisory only; no AI output affects metric definitions, computed values, or approval states |
| N/llm constrained scope | In the v3 report layout conversion feature, N/llm is constrained to template selection output only — it does not generate raw SuiteQL. This is a hard architectural constraint. |
For completeness — items that a technical reviewer might check:
N/http or N/https to call external services during normal metric computationThis document is maintained alongside the product and updated as the API inventory and compliance posture evolve. For questions, contact via tesserabi.com.