Build with Phasoric

Public contracts for handoffs, hosted APIs, MCP, automation, partner products, and governed extensions.

approved partner preview
View Markdown

Product Runtime

Machine-readable runtime reference

Phasoric Product Runtime is the supported application boundary between product experiences and the Phasoric intelligence/storage platform.

Hosted Markdown Vault integrations use the workspace and logical-Vault routes under /workspaces/:workspaceId/vaults/:vaultId. In addition to bounded note listing, content reads, and single-note publication, authorized products can preview and apply atomic multi-note mutations at POST /notes/transactions. The transaction accepts the canonical write-note, delete-note, and restore-note actions; rename and move are one atomic write-new plus delete-old transaction. Applied mutations require notes.publish, expected revisions for existing content, and an idempotency key. Deletes enter the hosted Vault trash rather than bypassing the canonical recovery path. Authorized readers can list content-free trash metadata at GET /notes/trash; restoring requires the trash ID and original path in a previewed restore-note transaction.

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 Phasoric React components, contexts, Dexie records, or internal vertical modules as its application contract. Product Runtime provides a narrower, versioned surface.

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. Phasoric 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. Phasoric 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-Phasoric-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. Phasoric 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. Phasoric 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. Phasoric 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 Phasoric'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. Phasoric 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. Phasoric 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. Phasoric 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 Phasoric account. Configure organization.settings.productRuntime through System Operations:

{
  "apiOperationsPerMonth": 1000000,
  "intelligenceBudgetMicrodollarsMonthly": 50000000,
  "maxConcurrentIntelligence": 20,
  "mediaStorageBytes": 524288000
}

In System Operations, open the calling product organization and use Product Runtime API operations per month. Leave the field blank to omit the operation cap, set a positive integer for a monthly ceiling, or set 0 only when Product Runtime access should be paused. The organization screen shows current-month usage before the setting is saved.

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. Phasoric 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 Phasoric records the underlying execution against the ClassLattice product organization; an educator's personal Phasoric 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. Phasoric 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

Phasoric 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 Phasoric 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 Phasoric Hosted data and explicit authorization.

Human developer access is account/workspace/vault bounded. Installed product access is bounded by the stronger chain:

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 Phasoric publishes a supported external package/distribution and partner credential flow.

Do not instruct arbitrary external developers to deep-import source files from the Phasoric 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 Phasoric connection ID and provider object lineage; OAuth tokens remain encrypted inside Phasoric.

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.