@plasius/spellcraft

Academy-gated spellcraft access, authoring, and validation boundary contracts for Plasius.

Apache-2.0. ESM + CJS builds. TypeScript types included.

Installation

npm install @plasius/spellcraft

Scope

@plasius/spellcraft owns the authority-side boundary for:

• spellcraft access state
• academy-gated authoring readiness
• declaration preview metadata
• Player System to spellcraft authority handoff payloads
• spellcraft-owned validation and execution authority metadata
• privacy-safe specialization payloads and spellcraft throughput assumptions
• specialization decision telemetry records
• performance budget metadata for decision evaluation paths

Player System Handoff

The Player System may explain readiness, route a player toward academy gates, and collect intent, but it does not become the source of truth for spell authoring. Once a user crosses the academy gate, the handoff into @plasius/spellcraft must carry the feature flag, guidance source, academy track, readiness outcome, and requested authoring mode so spellcraft remains the authoritative validation and execution boundary.

Demo

npm run build
node demo/example.mjs

Usage

import {
  createSpecializationDecisionTelemetryEvent,
  createSpellcraftAccessState,
  createSpellcraftGuidanceHandoff,
  createSpellcraftPerformanceBudget,
  createSpellcraftSpecializationRecord,
  defaultSpellcraftThroughputAssumptions,
  spellcraftAuthorityBoundary,
  spellcraftPrivacyScaleRollout,
} from "@plasius/spellcraft";

const access = createSpellcraftAccessState({
  academyEligible: true,
  authoringMode: "guided",
  declarationFormatVersion: "1.0.0",
});

const handoff = createSpellcraftGuidanceHandoff({
  authorityOwner: spellcraftAuthorityBoundary.authorityOwner,
  featureFlagId: spellcraftAuthorityBoundary.featureFlagId,
  guidanceSource: "player-system",
  academyTrack: "academy.evocation",
  readiness: "eligible",
  declarationFormatVersion: access.declarationFormatVersion,
  requestedAuthoringMode: access.authoringMode,
  handoffSummary:
    "Player System guidance has confirmed academy readiness and is yielding authority to spellcraft.",
});

const specialization = createSpellcraftSpecializationRecord({
  casterSubjectId: "caster-sub-1",
  academyNodeId: "academy-1",
  specializationId: "sigil-weaving",
  authoringMode: access.authoringMode,
  declarationFormatVersion: access.declarationFormatVersion,
  updatedAtIso: new Date().toISOString(),
});

const budget = createSpellcraftPerformanceBudget({
  stage: "declaration-validation",
  targetP95Ms: 75,
  hardTimeoutMs: 150,
  cacheable: false,
  maxDependencyCalls: 2,
});

const event = createSpecializationDecisionTelemetryEvent({
  decisionId: "decision-1",
  stage: "authoring-mode-selection",
  outcome: "allowed",
  durationMs: 32,
  academyEligible: access.academyEligible,
  authoringMode: access.authoringMode,
  declarationFormatVersion: access.declarationFormatVersion,
  observedAt: new Date().toISOString(),
});

console.log(spellcraftPrivacyScaleRollout.featureFlagId);
console.log(defaultSpellcraftThroughputAssumptions.maxDeclarationValidationsPerMinute);
console.log(handoff.guidanceSource, specialization.specializationId);
console.log(budget.targetP95Ms, event.stage);

Privacy And Throughput Baseline

The package exports an inherited rollout descriptor for the cross-repo feature flag isekai.training-progression.privacy-scale.enabled.

When that rollout is enabled, package consumers should prefer the minimal SpellcraftSpecializationRecord contract:

• casterSubjectId is the only player-linked identifier and is expected to be pseudonymous
• profile names, chat text, raw spell declarations, and contact data are outside the package contract
• spellcraftFieldPolicies documents the retention and sensitivity expectation for every exported specialization field
• defaultSpellcraftThroughputAssumptions publishes the validated authoring, specialization, and declaration-validation envelope used by the package docs and tests

Governance

• ADRs: docs/adrs
• TDRs: docs/tdrs
• Design notes: docs/design