--- title: Product Runtime description: Build an independent or first-party product over Basalt's stable runtime DTOs without depending on React, Dexie, or internal vertical modules. slug: product-runtime path: /product-runtime section: Platform availability: approved-partner-preview nav_order: 8 canonical_url: https://developers.basaltnotes.com/product-runtime markdown_url: https://developers.basaltnotes.com/product-runtime.md mirror_url: https://basaltnotes.com/developers/product-runtime --- # Product Runtime [Machine-readable runtime reference](/api/content/developers/references/product-runtime.json) Basalt Product Runtime is the supported application boundary between product experiences and the Basalt intelligence/storage platform. It keeps four responsibilities separate: 1. **Vertical Intelligence Packs** define domain semantics and deterministic intelligence. 2. **Product Experience Packs** define serializable presentation, navigation, terminology, onboarding intent, and capability visibility. 3. **Product Runtime** exposes versioned DTOs and operations over local or hosted adapters. 4. **Organization Brand Profiles** apply bounded presentation overrides after authorization is resolved. ## Why use Product Runtime An independent product should not import Basalt React components, contexts, Dexie records, or internal vertical modules as its application contract. Product Runtime provides a narrower, versioned surface. ```text Product Experience ↓ BasaltProductRuntime ↓ LocalRuntimeAdapter OR HostedRuntimeAdapter ↓ versioned DTO envelopes ``` ## Runtime version The current runtime contract is V1. Hosted callers can declare the supported version using the runtime-version request contract; unsupported versions fail explicitly rather than silently changing response shape. ## SDK shape The current SDK class exposes operations including: - `getRuntimeContext()` - `getCapabilities()` - `getWorkspace()` - `getDomainComposition()` - `listNotes()` / `readNote()` / `publishNote()` - `bindHostedVault()` - `listAvailableScopes()` - `getScopeContext()` - `getEffectiveScopePolicy()` - `getScopeIntelligence()` - `getScopeMemory()` - `createSharedMemoryCandidate()` - domain-specific projection methods currently used by the Education reference product - bounded Education Intelligence projection for installed products with the `intelligence.execute` service-principal scope - Pulse/decision/Forge operations where the active adapter supports them. Unavailable capabilities return explicit unavailable/partial envelopes where possible rather than fabricating data. ### Education Intelligence projection Installed education products may submit bounded, portable Education entities and provenance-backed relationships to `POST /api/product/v1/intelligence/education/projection`. Basalt owns contract normalization, deterministic evaluation, finding identity, and Decision Signal handoff. The caller must use an installation service-principal credential with `intelligence.execute`; a Product Experience hostname or client-supplied audience is never authority. The same scope authorizes `POST /api/product/v1/intelligence/education/generate`. The installed product supplies bounded workflow intent, authorized standards, course metadata, and explicitly selected sources. Basalt owns prompt construction, prompt-injection containment, provider dispatch, ordered fallback routing, model identity, and the cost-and-token usage receipt. Send `Accept: application/x-ndjson` plus `X-Basalt-Runtime-Version: 1` for `ready`, incremental `delta`, and final `done` events; disconnecting cancels the upstream request. JSON remains available for non-interactive server operations. Education-safe raster generation is available at `POST /api/product/v1/intelligence/education/generate-image`. It accepts bounded plan, teach, create, and communicate contexts plus a normalized educator visual brief: diagram/illustration/timeline/map/scene/organizer type, classroom audience, approved style, orientation, palette, required elements, exclusions, and accessibility alt-text intent. It returns PNG, JPEG, or WebP bytes with accessible alt text and the same organization-level usage receipt. Basalt owns the brief interpretation, safety framing, and image provider boundary; an installed product must not introduce its own prompt or provider-key path. Teacher-controlled learner scaffolding is available at `POST /api/product/v1/intelligence/education/student-guidance`. It requires an explicit elementary, middle, or secondary age band; an authorized course and standard; the live teacher-authored activity; a fail-closed policy that forbids answer revelation, external links, and direct messaging; and a teacher-visible transcript commitment. Basalt treats the learner message, support preferences, and prior turns as untrusted evidence. It can return a short hint, explanation scaffold, reflection question, explicit-locale translation, or clearer-reading version while preserving the learning demand and withholding the completed answer. Every result attaches explicit safety and organization-level usage receipts. The installed product remains responsible for roster authorization, transcript persistence, retention, escalation policy, customer credits, and live student-safety validation before enabling the capability. Reuse-first education products may call `POST /api/product/v1/intelligence/education/artifacts/recommend` with at most 250 candidates that the product has already authorized for its active user. Basalt Artifact Intelligence ranks goal, standard, course, format, and educator-accepted status; detects likely near-duplicate candidates; and recommends reuse, adaptation, translation, differentiation, or format conversion. The response contains stable IDs and explainable signals, never submitted artifact content. This deterministic operation requires the installation service principal's `intelligence.execute` scope and extends Basalt's shared intelligence layer rather than creating a product-local ranking engine. Standards products may call `POST /api/product/v1/intelligence/education/standards/crosswalk` with two already-authorized, bounded framework slices. Basalt compares CASE identity, normalized codes, statements, grades, subjects, and domains and returns deterministic candidates with confidence, signals, and a review rationale. It does not return submitted statements or apply standards authority. The installed product must persist candidates as proposals and require qualified human review before they can ground instruction. Evidence-informed retrieval practice is available at `POST /api/product/v1/intelligence/education/practice-review`. The installed product supplies one authorized course and standard, an explicit two-to-five-session cadence, and teacher-confirmed aggregate evidence only. Basalt returns bounded poll, short-answer, and sort proposals with educator-only answer guides, standards rationales, cautions, and a review checklist. It never receives learner identity, assigns learners, changes a calendar, grades, changes mastery, or makes placement or intervention decisions. The installed product owns persistence, edits, educator approval, roster assignment, learner delivery, response review, and customer-facing credits. The projection is read-only and does not create trusted memory or execute Forge mutations. Learner evidence remains subject to the product's existing scope and privacy controls before submission, and consequential decisions remain human-owned. ### Private education media Installed education products may store bounded student-response audio with `POST /api/product/v1/intelligence/education/media/audio` (`media.write`) and stream it with `GET /api/product/v1/intelligence/education/media/:mediaId` (`media.read`). Uploads require an idempotency key, an opaque product media reference, a declared duration, and WebM, Ogg, or MP4 bytes. Basalt validates the file signature, limits audio to 3 MiB and 120 seconds, records SHA-256, stores the object privately, and authorizes every read by the same organization and installation. It never returns a Blob URL or storage credential. `organization.settings.productRuntime.mediaStorageBytes` is the shared storage ceiling for every installation in that product organization; the default is 500 MiB. The product remains responsible for its roster and course authorization, accessible recording UI, evidence review, retention/legal holds, and export policy. Declared duration is bounded but is not a decoded-media attestation; deployment verification must exercise real browser recordings and storage reconciliation. ### First-party API and Intelligence allowances First-party allowances belong to the calling product organization, not to an individual Basalt account. Configure `organization.settings.productRuntime` through System Operations: ```json { "apiOperationsPerMonth": 1000000, "intelligenceBudgetMicrodollarsMonthly": 50000000, "maxConcurrentIntelligence": 20, "mediaStorageBytes": 524288000 } ``` `intelligenceBudgetMicrodollarsMonthly` is the internal provider-cost ceiling; `1,000,000` microdollars equals one US dollar. It is shared across every installation owned by the organization. An installation may define a lower `configuration.productRuntime.intelligenceBudgetMicrodollarsMonthly` sublimit. A missing or zero organization Intelligence budget fails closed. Generation calls require an `Idempotency-Key`. Basalt reserves the maximum bounded request cost before provider dispatch, settles actual provider cost and token usage afterward, and returns a `basalt.product-intelligence-usage` receipt. Requests rejected before provider acceptance release capacity. Accepted requests with an interrupted or ambiguous completion are conservatively recorded as billable failures; they are not released as free work. Expired undispatched reservations release capacity. Retried settled requests replay the stored result without a second model call. Customer-facing credits remain the calling product's responsibility. ClassLattice reserves and settles ClassLattice AI Credits while Basalt records the underlying execution against the ClassLattice product organization; an educator's personal Basalt balance is never involved. ClassLattice Education workflows can attach the optional `classlattice.education-context` version 1 object to supported structured, generic, and image generation requests. ClassLattice remains responsible for current organization/course/standards/Vault authorization and source-revision checks. Basalt bounds the packet again, rejects learner-specific record language, and accepts only aggregate class-support categories meeting a minimum group size of five. The context is advisory and cannot authorize consequential decisions. Omitting it remains backwards compatible. ### Education quality evaluation Basalt owns the reusable Education generation evaluator and representative scenario suite. Run fixture validation with `npm --prefix server run eval:education`. Set `BASALT_EDUCATION_EVAL_LIVE=1` in an authorized evaluation environment to execute the scenarios against the configured hosted model. The suite currently covers weekly planning, assessment, reuse-first adaptation, evidence-to-reteach, live whiteboard preparation, writing feedback, family communication, and substitute continuity. The evaluator records standards and source visibility, teacher-review language, checks for understanding, accessibility, consequential-decision safety, privacy safety, latency, and first-party usage-receipt integrity. It is a release-quality signal, not proof of educator acceptance or production instructional outcomes; those require reviewed evaluation sets and live teacher studies. ## Local adapter The local adapter works against the active local Basalt workspace/vault state and preserves offline/local-first behavior. It should not upload local content merely because an independent product wants hosted symmetry. ## Hosted adapter Hosted runtime operations work only against Basalt Hosted data and explicit authorization. Human developer access is account/workspace/vault bounded. Installed product access is bounded by the stronger chain: ```text organization + product definition + customer installation + service principal + credential scopes + organization workspace assignment + logical-vault grant ``` All required links must authorize the operation. ## Presentation is not authority This is a permanent platform invariant: > Product Experience identity, hostname, branding, and product identity are presentation inputs only. They do not grant entitlement, organization membership, workspace access, logical-vault access, or governance authority. A custom branded host can resolve safe public presentation without gaining access to tenant data. ## Hosted note publishing Hosted note publication uses the same knowledge-transaction principles as the Developer API: - preview before apply where the operation exposes a preview path; - idempotency for applied writes; - current revision for updates; - explicit logical-vault grant; - revocation without deleting the user's content. ## Context Scopes Product Runtime composes with Context Scopes for shared intelligence. Hosted callers provide a stable scope ID; the server resolves the current audience, workspace/vault authority, explicit grants, and inherited policy. External service principals cannot manufacture a human audience or shared grant. ## First-party versus partner usage The runtime exists in production architecture today, but public third-party packaging/onboarding should be described as **approved partner preview** until Basalt publishes a supported external package/distribution and partner credential flow. Do not instruct arbitrary external developers to deep-import source files from the Basalt repository as a long-term SDK installation mechanism. ## Delegated Google Workspace connections Installed first-party products can use `connections.manage` for OAuth lifecycle and `connections.execute` for bounded Drive and Google Classroom round trips. Register the product's HTTPS return origin or exact redirect URI on its Product Definition, then register `${APP_URL}/api/product/v1/connections/google/oauth/callback` in the Google OAuth client. External products store only the returned Basalt connection ID and provider object lineage; OAuth tokens remain encrypted inside Basalt. The Drive contract supports retry-safe create/update and bounded import. An update includes the last observed provider version. A mismatch returns a conflict instead of overwriting remote work. Requesting OAuth services `['drive', 'classroom']` adds the least-privilege Classroom course-read, roster-read, and teacher-coursework scopes used by the runtime. The Classroom contract lists the authorized teacher's active courses and roster, creates retry-safe assignments, and lists bounded submission attachment metadata. It deliberately omits profile emails and grades and exposes no grading mutation. The caller owns local course authorization, roster identity confirmation, standards and artifact lineage, education-record retention, and human evidence review. ### Education assessment drafting Installations with `intelligence.execute` can call `POST /api/product/v1/intelligence/education/assessment-draft`. Supply bounded course context, authorized standards and reviewed learning targets, optional reviewed sources, item count/types, target DOK levels, and accessibility requirements. The metered response kind is `education-assessment-draft`; its `basalt.education-assessment-draft` data contains a strict structured draft and a usage receipt. Consumers must keep it in a proposed state until an authorized educator reviews it. Installations with `intelligence.execute` can call `POST /api/product/v1/intelligence/education/quality-review`. Supply one bounded artifact revision, its authorized course and adopted standards, authorized supporting sources, applicable policy constraints, and optional shared Education Context. The metered response kind is `education-quality-review`; its `basalt.education-quality-review` data evaluates alignment, source support, citations, reading level, accessibility, bias risk, assessment validity, and policy conflicts. The result is advisory and requires educator review. Consumers retain authorization, local policy authority, persistence, override decisions, and approval. ### Education rubric drafting Installations with `intelligence.execute` can call `POST /api/product/v1/intelligence/education/rubric-draft`. Supply bounded course context, authorized standards and reviewed learning targets, optional reviewed sources, criterion count, 2–6 ordered level labels, and accessibility requirements. The metered `basalt.education-rubric-draft` response contains weighted analytic criteria and observable descriptors. Consumers must persist it as a proposed, versioned instrument and require educator review before reuse; the response never applies the rubric to a learner or creates a grade or mastery decision.