Seshat Domain — Technical Specifications

Technical specification for the Seshat dwelling-arts and craftsmanship domain: domain objects, enums and literal-union types, computation result shapes, validation schemas, the project state machine, configuration, and module surfaces. Every entity, field, enum value, and function named below is traceable to source under libs/seshat/*.

This document is the authoritative reference for engineers integrating with or extending Seshat. It lists the precise names, types, and constraints for every schema, enum, function, and constant exposed by the domain's eleven libraries. Where the features document explains what something does and why, this document specifies exactly how it is shaped — field types, valid values, error codes, state machine transitions.

Status#

Implemented as eleven TypeScript libraries under libs/seshat/. There is no apps/seshat or services/seshat — Seshat ships purely as importable libraries with no runtime service, no HTTP/API gateway, and no event bus. The TODOS Phase 36 backlog (TODOS.md) describes an API gateway and event infrastructure as future scope; none of that is present in the workspace.

Technology Stack#

The table below lists the technology choice for each layer of the domain. The most important constraint for integration is the runtime: only zod (and uuid for @seshat/core) — no database drivers, no HTTP clients, no message bus adapters.

Every libs/seshat/*/package.json declares exactly one runtime dependency, zod, and one dev dependency, vitest. @seshat/core additionally imports uuid. No library depends on any @oshun/* package or on a database driver, message bus, or AI runtime.

Library Structure (11 Libraries)#

The following table maps each library to its npm package name and primary responsibility. The dependency direction is important: every domain library may import from @seshat/common; @seshat/database deliberately imports nothing from the other domain libraries; @seshat/core does not import the other domain libraries at runtime — it references them only as identifier strings.

Dependency direction: every domain library imports types from @seshat/common; @seshat/database defines its own Zod schemas without importing @seshat/common (a deliberate decoupling, per its file header). @seshat/core does not import the other domain libraries — it lists them only as identifier strings in SeshatModuleSchema / MODULE_CAPABILITIES.

Domain Orchestration (@seshat/core)#

Project Entity#

The ProjectSchema is the central entity for tracking a dwelling-arts project through its lifecycle. Budget is tracked in integer cents to avoid floating-point rounding errors. The roomIds array links a project to the physical spaces it concerns.

ProjectSchema (Zod object, core/src/types.ts):

Budget = { allocatedCents: int ≥0, spentCents: int ≥0, currency: 3-char, default "USD" }. Budget is tracked in integer cents.

CreateProjectInputSchema picks name, category, ownerId and re-adds optional description, priority, budget, tags, targetDate.

Project Enums#

These enums control the type and lifecycle of a project. Note that ProjectPhase here is the eleven-value core lifecycle enum; a separate ten-stage craft-phase union exists in @seshat/common for woodworking-specific project phases — they are distinct concepts serving different purposes.

ProjectCategory =
  | 'interior_design' | 'woodworking' | 'renovation' | 'spatial_harmony'
  | 'smart_dwelling' | 'fabrication' | 'craft' | 'workshop_setup';

ProjectPhase =
  | 'concept' | 'planning' | 'design' | 'material_sourcing' | 'fabrication'
  | 'assembly' | 'finishing' | 'installation' | 'review' | 'completed'
  | 'archived';

ProjectPriority = 'low' | 'medium' | 'high' | 'urgent';

Project Phase State Machine#

ProjectManager (core/src/project-manager.ts) is an in-memory Map-backed store. Phase transitions are strictly controlled by VALID_TRANSITIONS, shown below. The design allows any non-archived phase to revert to planning for rework — this reflects the reality that dwelling projects frequently cycle back when design iterations reveal problems. The archived state is terminal.

transitionPhase enforces VALID_TRANSITIONS:

Any phase may revert to planning for rework, and any non-archived phase may move to archived. Invalid transitions throw InvalidPhaseTransitionError. recordExpense throws BudgetExceededError when spentCents + amount would exceed allocatedCents. Helpers: isValidTransition, getNextPhases. ProjectManager methods: create, get, list (filter by category / phase / ownerId / tag), transitionPhase, recordExpense, getBudgetUtilization, delete, count, clear.

Workflow DAG Engine#

The workflow engine models a project as a directed acyclic graph of steps, where steps can only begin when their dependencies are complete. This prevents out-of-order execution — for example, you cannot begin finishing until assembly is complete, and you cannot begin assembly until material_sourcing is done.

Workflow = { id (UUID), projectId (UUID), steps: WorkflowStep[], createdAt }. WorkflowStep = { id, name, description?, status: StepStatus, phase: ProjectPhase, dependsOn: string[], estimatedMinutes?, actualMinutes?, module? }.

StepStatus = 'pending' | 'in_progress' | 'blocked' | 'completed' | 'skipped'.

workflow-engine.ts provides pure DAG functions:

• detectCycle / topologicalSort — Kahn's algorithm; topologicalSort throws CycleDetectedError on a cycle.
• isStepReady, getReadySteps, getBlockers — dependency readiness.
• computeProgress → WorkflowProgress (totalSteps, completedSteps, skippedSteps, inProgressSteps, blockedSteps, pendingSteps, completionPercentage, estimatedRemainingMinutes).
• transitionStep — validates against VALID_STEP_TRANSITIONS; throws WorkflowStepBlockedError when starting a step with unmet dependencies.
• generateWorkflow — builds a sequential-dependency workflow from a phase list.

WorkflowTemplate + WORKFLOW_TEMPLATES define a default phase sequence per ProjectCategory (8 templates); getWorkflowTemplate(category) looks one up.

Module Registry#

The module registry is a capability discovery mechanism. Rather than importing all Seshat libraries at once, an application can query which modules are available and what they can do before deciding which to load.

SeshatModule enum: harmony, design, craft, academy, smart, workshop, fabrication, sustainability, common, database. MODULE_CAPABILITIES maps each module to a readonly string[] of capability identifiers (e.g. harmony → ['feng_shui', 'vastu_shastra', 'biophilic_design', 'sacred_geometry', 'bagua']). ModuleHealth is a type (module, status, latencyMs, lastCheckedAt) with no runtime probe.

Configuration#

SeshatConfigSchema composes six section schemas — one per major subsystem — each defaulting to an empty object when no configuration is provided. This means Seshat works out of the box with zero configuration, and features can be enabled progressively.

The six section schemas are harmony, design, craft, smart, fabrication, and sustainability. Notable section fields include:

• HarmonyConfig.defaultTradition (feng_shui|vastu_shastra|biophilic|western)
• DesignConfig.renderQuality (draft|standard|high|photorealistic) and arEnabled
• SmartConfig.mqttBrokerUrl (optional URL) and devicePollingIntervalMs
• FabricationConfig.cncSupportEnabled, print3dSupportEnabled, materialWasteThresholdPct
• SustainabilityConfig.localRadiusKm

ConfigManager holds the validated config in memory: get, getSection, update (deep-merges then re-validates), onChange (returns an unsubscribe function), reset. createConfigFromEnv reads SESHAT_SECTION_KEY-style environment keys, coercing true/false/integers/floats.

Errors#

All Seshat errors extend SeshatError, which carries a numeric code, a severity level, and a structured context record. The numeric codes are grouped by functional area so that error monitoring can route by area without parsing the message string.

SeshatError extends Error carries code (SeshatErrorCodeValue), severity (SeshatErrorSeverity enum: info|warning|error|critical), and a context record; toJSON() serialises it. SeshatErrorCode is a numeric code map grouped by area:

• Project: 1001–1004
• Workflow: 2001–2004
• Module: 3001–3003
• Config: 4001–4002
• Validation: 5001–5003
• Feature Flags: 6001–6002

Concrete subclasses: ProjectNotFoundError, InvalidPhaseTransitionError, BudgetExceededError, WorkflowStepBlockedError, CycleDetectedError, ModuleUnavailableError, FeatureDisabledError. Type guard: isSeshatError.

Logging#

SeshatLogger is a self-contained structured logger (no Pino dependency). LOG_LEVELS: trace 10 … fatal 60. Emits SeshatLogEntry objects to one or more LogSink functions; defaultConsoleSink writes JSON to the console, MemoryLogSink captures entries for tests. child() creates a logger with extended context. Base context is always { domain: 'seshat' }.

Feature Flags#

The feature flag system controls capability exposure per user without branching library code. The percentage rollout uses a deterministic FNV-1a hash keyed on userId, so a given user always gets the same result for a given flag — this prevents the "flag flipping" experience where a feature appears and disappears on successive page loads.

FeatureFlagManager evaluates flags with deterministic FNV-1a-hash percentage rollout keyed on userId, plus manual overrides. SESHAT_FEATURES defines 10 flags:

• HARMONY_FENG_SHUI_V2
• HARMONY_VASTU_SHASTRA
• DESIGN_AR_PREVIEW
• DESIGN_PHOTOREALISTIC_RENDER
• CRAFT_AI_JOINERY
• SMART_DWELLING_MQTT
• FABRICATION_CNC
• FABRICATION_3D_PRINT
• SUSTAINABILITY_CARBON_TRACKING
• ACADEMY_MENTORSHIP_MATCHING

evaluate returns { key, enabled, reason } where reason is one of override, rollout-all, rollout-none, rollout-hash, default, unknown.

Shared Types & Constants (@seshat/common)#

@seshat/common exports an extensive type vocabulary plus real-world constant databases. It declares the platform identity in its header as eight pillars: Spatial Harmony, Interior Design, Craftsman's Forge, Maker's Academy, Smart Dwelling, Workshop Management, Digital Fabrication, Sustainability.

Branded ID & Measurement Types#

Type safety for IDs prevents accidentally passing a RoomId where a ToolId is expected. Branded types give compile-time guarantees beyond what a plain string provides.

Branded string IDs: ProjectId, MaterialId, ToolId, DeviceId, RoomId, FloorId, BuildingId, UserId, CourseId, LessonId, AutomationId. Measurement: LengthUnit, AreaUnit, VolumeUnit (includes board_feet), AngleUnit, TemperatureUnit, WeightUnit; generic Measurement<U> and its aliases.

Geometry Types#

These geometry primitives are the lowest-level shared vocabulary. They appear in floor plan analysis, Feng Shui chi flow simulation, fabrication nesting, and parametric design — a single consistent set prevents duplicate type hierarchies across libraries.

2D: Point2D, Vector2D, BoundingBox2D, Polygon2D, LineSegment2D, Dimensions2D. 3D: Point3D, Vector3D, BoundingBox3D, Dimensions3D, EulerAngles, Transform3D.

Spatial / Architectural Types#

CompassDirection (8-point), CardinalDirection, IntercardinalDirection, CompassBearing. RoomType is a 26-value union (bedroom, bathroom, kitchen, … attic, basement). Room, DoorOpening, WindowOpening, Floor, Building, FloorPlan describe a building hierarchy. Building carries orientation (degrees from true north), optional latitude / longitude / yearBuilt, and buildingType (residential|commercial|mixed|industrial|institutional).

Feng Shui & Vastu Types#

These types implement the conceptual vocabulary of both traditions, enabling harmony analysis functions to produce richly typed results that downstream code can inspect without string parsing.

BaguaArea (9 values: wealth, fame, love, family, health, creativity, knowledge, career, helpful_people). FiveElement (wood|fire|earth|metal|water). ElementCycle (generating|controlling|weakening|insulting). FlyingStarNumber (1–9), FlyingStar, FlyingStarChart, KuaNumber. ChiFlowType (sheng_chi|sha_chi|si_chi). FengShuiRemedyType (14 values). FengShuiAnalysis, BaguaAreaAssessment.

Vastu types: VastuDirection (9), VastuPada (17-value Purusha Mandala union: ishanya, parjanya, … soma, brahma). VastuElement (prithvi|jala|agni|vayu|akasha). VastuDevta, VastuDefectType (12), VastuRemedy, VastuZone, VastuAnalysis.

Design Philosophy Types#

WabiSabiPrinciple (7: fukinsei, kanso, koko, shizen, yugen, datsuzoku, seijaku). HyggeElement (12). BiophilicPattern (14, Terrapin Bright Green framework). BiophilicPatternInfo. SacredGeometryType (10). SacredGeometry. PlatonicSolid (5). PlatonicSolidInfo.

Material, Joinery, Tool & Project Types#

The material and joinery type system is especially rich because it encodes woodworking knowledge directly into types — a function that accepts WoodSpecies gets automatic IDE documentation for every property the species carries.

MaterialCategory (17). GrainPattern (8). GrainDirection (4). MaterialGrade (FAS|select|no1_common|no2_common|no3_common|utility). WoodMoistureContent. WoodWorkability (nine 1–10 sub-ratings). WoodSpecies (full physical-property record). FinishType (14). FinishInfo. AdhesiveType (10). AdhesiveInfo.

JointType is a 30-value union spanning Western, Japanese (sashimono, kumiko, kanawa_tsugi, kawai_tsugi, okkake_daisen_tsugi) and Chinese (mitered_mortise_tenon, cloud_lift_panel) joinery, along with JointTradition, JointStrength (tensile/shear/compression/racking/overall rated 1–10), JointDifficulty (1–10), JointInfo, CuttingSequence, CuttingStep.

ToolCategory (29 values). ToolPowerSource. HandTool, PowerTool, CNCTool. ToolCondition. MaintenanceSchedule. MaintenanceTask.

Project domain: ProjectDifficulty (beginner|intermediate|advanced|master). ProjectType (15). ProjectPhase (a 10-stage craft-phase union, distinct from @seshat/core's phase enum — these are craft-specific phases, not lifecycle phases). Project, CutList, CutListItem, BillOfMaterials, HardwareItem, MaterialEstimate, FinishEstimate, AdhesiveEstimate.

IoT / Smart Home Types#

SmartDeviceType (8). SensorType (15). DeviceProtocol (9: zigbee, zwave, wifi, bluetooth, thread, matter, lora, modbus, knx). SmartDevice, SensorReading. AutomationTriggerType (9). AutomationTrigger. AutomationActionType (7). AutomationAction, AutomationRule, HomeEnvironment.

Design / Visualization Types#

DesignStyle (24-value union, covering all major Western and Eastern interior design styles). ColorHarmony (6). RGBColor, HSLColor, DesignColor, ColorPalette. RenderQuality (draft|preview|standard|high|production). RenderFormat. MoodBoardItem, DesignBrief, DesignStyleInfo.

Sustainability, Learning & Fabrication Types#

Sustainability: SustainabilityRating (A–F). CertificationType (10: fsc, pefc, cradle_to_cradle, greenguard, leed, breeam, well, living_building_challenge, energy_star, blue_angel). CarbonFootprint, LifeCycleAssessment. CircularDesignPrinciple (10). SustainabilityAssessment.

Learning: SkillLevel (novice…master, 6 levels). AssessmentType (7). CertificationLevel (foundation|practitioner|professional|master|grand_master). LearningPath, CourseModule, LessonPlan, StudentProgress.

Fabrication: CNCOperationType (9). PrintMaterial (9). GCodeCommand, CNCToolpath, PrintSettings, LaserSettings.

Events Type (declaration only)#

The event types below describe the domain events Seshat could emit if an event bus were wired up. They are pure type declarations — no publisher, subscriber, or transport exists in any libs/seshat/ library. They appear here so that the Phase 36 event infrastructure can be implemented against a pre-agreed type contract.

SeshatEventType is a 12-value union:

• project_created, project_updated, project_completed
• material_added, material_depleted
• tool_maintenance_due
• sensor_alert, automation_triggered
• lesson_completed, certification_earned
• design_saved, render_completed

SeshatEvent<T> is a generic envelope wrapping a payload of type T.

Constant Databases#

common/src/constants.ts ships curated reference data used across all libraries. These are real-world values, not placeholders — wood species properties come from the Wood Handbook (USDA Forest Products Laboratory); joint strength ratings from woodworking technical literature; protocol specs from manufacturer documentation.

• WOOD_SPECIES — keyed record of 30 wood species with real Janka hardness, density, shrinkage, and per-operation workability ratings.
• BAGUA_AREAS (9 entries), ELEMENT_CYCLES (20 element-pair relations across all four cycles), VASTU_ZONES (9 directional zones).
• GOLDEN_RATIO, FIBONACCI_SEQUENCE (first 20), SACRED_GEOMETRY (10 entries), PLATONIC_SOLIDS (5).
• COLOR_PSYCHOLOGY (21 colours with emotions, cultural meanings, Feng Shui element), BIOPHILIC_PATTERNS (14 patterns with stress-reduction / cognitive-performance scores), DESIGN_STYLES (24 style profiles), JOINT_DATABASE (20 joints with strength ratings).
• COMPASS_DEGREES, COMPASS_DIRECTIONS, LENGTH_TO_MM, WEIGHT_TO_G, JANKA_CATEGORIES, CERTIFICATIONS (10), SKILL_LEVEL_HOURS (6 tiers), DEVICE_PROTOCOL_SPECS (9 protocols with frequency / range / mesh support).

Utility Functions#

common/src/utils.ts exports pure functions covering the mathematical operations needed across all Seshat domains:

• Geometry: calculatePolygonArea (shoelace formula), pointInPolygon (ray-casting), polygonCentroid, lineIntersection, rotations, volume/area formulas.
• Measurement conversion: convertLength, convertArea, convertVolume, convertWeight, convertTemperature, convertAngle, boardFeetToVolume.
• Material maths: calculateBoardFeet, calculateMoistureExpansion (using a 28% fibre-saturation point), calculateWoodWeight, jankaHardnessCategory.
• Compass helpers: compass bearing and direction utilities.
• Colour: hexToRgb, rgbToHex, hexToHsl, hslToHex, colorContrast (WCAG ratio), generateColorPalette, blendColors.
• Proportion: isGoldenRatio, fibonacciSequence, harmonicProportion, ruleOfThirdsGrid.
• Scoring: normalizeScore, weightedAverage, letterGrade, difficultyLabel.

Craft Specifications (@seshat/craft)#

@seshat/craft is a pure-function woodworking knowledge engine. Domain types in craft/src/types.ts include the following. These are the local, extended types used inside the craft library, many of which extend or refine the base types from @seshat/common:

JointDetail (extends JointInfo with cutting sequence, common mistakes, tips, estimated time, optional angle), SashimonoJoint, KumikoPattern, DovetailSpec, MortiseTenonSpec, JointSelectionCriteria, JointSelectionResult, WoodIdentification, WoodComparison, GrainAnalysis, MoistureAnalysis, MaterialBillItem, BillOfMaterials, ToolProfile, SharpnessAssessment, CNCFeedSpeed, SandingProgression, FinishProfile, FinishCompatibility, FinishSelectionCriteria, FinishSelectionResult, WoodworkingProject, CutListItem, TimeEstimate, ProjectDifficultyAssessment, ProjectTemplate.

Joinery (joinery.ts)#

The joinery module contains three constant databases and five geometry computation functions, plus the joint selection wizard.

Constant databases:

• SASHIMONO_JOINTS — database of Japanese joints (e.g. ari-tsugi, kama-tsugi, hozo-sashi, kanawa-tsugi, kawai-tsugi), each with romanized/Japanese/English names, difficulty, strength ratings, cutting sequence, common mistakes, best use cases.
• KUMIKO_PATTERNS — geometric lattice patterns (asanoha, izutsu, kikko, sakura, …) with strip angles, strips-per-unit, symbolism.
• WESTERN_JOINT_DETAILS — extended JointDetail records for common Western joints; DOVETAIL_RATIOS and constants DRAWBORE_OFFSET_STANDARD (1/16") and DRAWBORE_OFFSET_DELICATE (1/32").

Geometry computations: calculateDovetailLayout (pin/tail positions), calculateMortiseTenonSize (tenon thickness/width/length, haunch), calculateDrawboreOffset, calculateBoxJoint, calculateKumikoNotch.

Selection / lookup: selectJoint (scored recommendations from JointSelectionCriteria), findSashimonoJoint, findKumikoPattern, getJointsByTradition, getJointsForApplication.

Materials, Tools, Finishing, Projects#

These modules are grouped here because each corresponds to a single source file. All functions are pure.

• materials.ts: getWoodSpecies, resolveSpeciesKey, compareSpecies, findSimilarSpecies, recommendSpecies, calculateEMC / calculateEMCCelsius (equilibrium moisture content), predictSeasonalMovement, analyzeMoisture, calculateDryingTime, analyzeCutOrientation, identifyWood, generateBOM.
• tools.ts: calculateFeedsAndSpeeds, calculateOptimalRPM, calculateSandingProgression, getFinishSandingGrit, getSharpnessAssessment, suggestToolUpgrade, getToolDatabase.
• finishing.ts: FINISH_DATABASE; getFinish, getFinishesByType, getFoodSafeFinishes, getLowVOCFinishes, selectFinish, checkFinishCompatibility, getFinishSandingGritByKey.
• projects.ts: PROJECT_TEMPLATES, constants STANDARD_KERF (0.125") and THIN_KERF (0.09375"); getProjectTemplate, getProjectsByCategory, getProjectsByJoint, generateCutList, estimateProjectTime, assessDifficulty.

Design Specifications (@seshat/design)#

@seshat/design has no Zod schemas and no AI runtime — it is pure functions over @seshat/common types producing structured analysis objects. The library models room visualisations as descriptive data structures (RoomVisualization, RenderSettings, MaterialSurface, VisualizationFurniture, LightingSource), not as image generation.

Key types defined in design/src/types.ts:

ParsedDesignBrief, DesignConstraint, StyleKeyword, TimeOfDay (8 values), CameraPerspective (7), DesignEra (13), StyleScore, StyleClassification, StyleInterpolation, StyleConsistencyResult, StyleDatabaseEntry, ParametricDefinition, ParametricConstraint, ParametricParameter, JointType (a design-local 12-value union), TopologyOptimization, DesignFitnessScore, DesignCandidate, GeneticDesignResult, VoronoiPattern, VoronoiCell, ShelvingSystem, ShelfSpec, FloorPlanAnalysis, RoomProportionScore, NaturalLightScore, TrafficFlowResult, FurnitureCategory (15), FurnitureItem, FurnitureLayout, ClearanceCheck, WorkTriangleResult, LayoutPreset, LayoutArrangement, MoodBoardAnalysis, ExtractedColor, StyleTag, BudgetEstimate, BudgetLineItem, ProductMatch, AccessibilityAudit.

Functions by area:

• Style: STYLE_DATABASE (record keyed by all 24 DesignStyle values); classifyStyle, checkStyleConsistency, interpolateStyles, getStyleInfo, getComplementaryStyles, getClashingStyles.
• Floor plan: CLEARANCE_STANDARDS, LAYOUT_PRESETS; analyzeFloorPlan, analyzeTrafficFlow, analyzeWorkTriangle, checkAccessibility, checkClearances, generateFurnitureLayout, getLayoutPresets, recommendLayoutPreset.
• Parametric: createParametricDesign, validateParametricConstraints, optimizeTopology, evolveDesign (genetic algorithm), generateVoronoiPattern, generateShelvingSystem.
• Mood board: analyzeMoodBoard, extractMoodBoardPalette, generateStyleTags, parseDesignBrief (rule-based natural-language parse).
• Product discovery: STYLE_MULTIPLIERS, QUALITY_MULTIPLIERS; matchProducts, classifyBudgetTier, estimateRoomBudget, compareBudgetTiers, getStyleMultiplier, getQualityMultiplier.

Fabrication Specifications (@seshat/fabrication)#

Pure functions, no Zod schemas. Types in fabrication/src/types.ts cover machines and tools, toolpaths/G-code, laser settings, 3D printing parameters, and nesting. Specific type groups:

• Machines and tools: CNCMachine, CuttingTool, ToolGeometry, ToolMaterial, ToolCoating, WorkpieceMaterial (21-value family list), FeedSpeedResult.
• Toolpaths/G-code: ToolpathSegment, CNCToolpathExtended, GCodeProgram.
• Laser: LaserMachineSpec, LaserCutSettings, LaserCutJob, LaserShape, LaserMaterial, LaserOperationMode, LaserSourceType.
• 3D printing: ModelMesh, PrinterProfile, PrinterTechnology, PrintJobSettings, PrintQuality, InfillPattern, SupportStrategy, AdhesionType, PrintTimeEstimate, MaterialUsageEstimate, PrintJob3D.
• Nesting: NestingPart, PlacedPart, NestingRotation, SheetDimensions, SheetNestingResult, NestingResult, CutOptimizationResult, OrderedCut.
• Digital twin (declared but not exercised): DigitalTwin, TwinError, SensorSnapshot, TwinSyncState. fabrication/src/index.ts exports no digital-twin functions and there is no digital-twin.ts module.

Implemented functions:

• CNC (cnc.ts): calculateFeedsAndSpeeds, generateGCode (returns a full GCodeProgram), optimizeToolpath, calculateKerfCompensation, estimateMachiningTime; tables SFM_TABLE, CHIP_LOAD_TABLE, UNIT_POWER_TABLE, constant MAX_DOC_FACTOR.
• Laser (laser.ts): calculateLaserSettings, generateLaserToolpath, calculateMaterialUsage (re-exported as calculateLaserMaterialUsage); table MATERIAL_PROFILES.
• 3D printing (printing3d.ts): calculatePrintSettings, estimatePrintTime, estimateMaterialUsage (as estimatePrintMaterialUsage); tables MATERIAL_DB, LAYER_HEIGHTS, constant DEFAULT_INFILL.
• Nesting (nesting.ts): nestParts (2D bin-packing), optimizeCutSequence, estimateSheetsRequired, calculateWasteWithKerf.

Harmony Specifications (@seshat/harmony)#

Pure functions producing detailed analysis objects. The result-type vocabulary in harmony/src/types.ts is large. The types are organized below by tradition.

Feng Shui types: BaguaAnalysis, BaguaSectorResult, FlyingStarChart, FlyingStarPalace, FlyingStarPeriod, FlyingStarInterpretation, KuaNumberResult, KuaDirectionSet, ChiFlowResult (with FlowFieldCell, StagnationZone, ShaChiSource, ChiEntryPoint, ChiFlowRemedy), ElementBalanceResult, PoisonArrowDetection, PoisonArrow, RoomFengShuiAnalysis.

Vastu types: VastuFullAnalysis, VastuPurushaMandalaResult, VastuMandalaCell, BrahmasthanaStatus, VastuDirectionResult, VastuRoomPlacementResult, VastuDefectResult, DwarVedhiResult, VastuRecommendation.

Philosophy, biophilic, geometry, colour types: WabiSabiAssessment, HyggeAssessment, BiophilicAssessment, BiophilicPatternScore, BiophilicRecommendation, PlantRecommendation, SacredGeometryAnalysis, GoldenSpiralResult, VesicaPiscisResult, FlowerOfLifeResult, ColorPsychologyReport (with 60-30-10 ColorProportionAnalysis, ColorTemperatureAnalysis, WCAG ColorAccessibilityAnalysis).

Synthesis types: HarmonyTradition (7-value union), HarmonySynthesis, TraditionConflict, TraditionAgreement, SynthesisRecommendation, SynthesisConfig.

Functions by source file:

• Feng Shui (feng-shui.ts): analyzeBagua, analyzeElementBalance, calculateFlyingStarChart, calculateAnnualStar, calculateKuaNumber, simulateChiFlow, detectPoisonArrows, analyzeBedroom, analyzeKitchen, analyzeHomeOffice, analyzeEntrance (exported as analyzeFengShuiEntrance), getPeriodForYear, element helpers (getGeneratingElement, getControllingElement, getGeneratedElement, colorToElement, materialToElement, shapeToElement).
• Vastu (vastu-shastra.ts): createVastuMandala, analyzeDirections, validateRoomPlacement, detectVastuDefects, analyzeEntrance (as analyzeVastuEntrance), performFullVastuAnalysis.
• Design philosophy (design-philosophy.ts): assessWabiSabi, assessHygge; HYGGE_ELEMENTS record.
• Biophilic (biophilic-design.ts): assessBiophilicDesign, recommendPlants.
• Sacred geometry (sacred-geometry.ts): analyzeProportions, generateGoldenSpiralPoints, generateVesicaPiscis, generateFlowerOfLife, isGoldenRatio, isFibonacciRatio, goldenDivision, goldenRectangleSubdivisions.
• Colour psychology (color-psychology.ts): analyzeRoomColors.
• Synthesis (synthesis.ts): synthesizeHarmony — weighted multi-tradition composite with conflict detection.

Smart Dwelling Specifications (@seshat/smart)#

Domain Types#

IoTDevice extends the base device type with groupIds, firmware (FirmwareInfo), signalStrength, capabilities (DeviceCapability[]), and metadata. DeviceStatus is a 7-value union: online, offline, error, pairing, updating, sleeping, initializing.

Supporting device types: DeviceHealth, DeviceFilter, DeviceGroup.

Sensor types: SensorReadingExtended (carries rawValue / calibratedValue and SensorQuality: excellent|good|degraded|poor|invalid). CalibrationParams, CalibrationPoint, SensorConfig, SensorThreshold, AnomalyResult, SensorFusionResult, SensorFusionSource.

Automation types: AutomationRuleDefinition (extends the base rule with triggerLogic: and|or, cooldownMs, schedule, and tags); AutomationTriggerExtended, AutomationActionExtended (webhook + notification fields), AutomationCondition, GeofenceConfig, AutomationSchedule, Scene, SceneDeviceState, RuleEvaluationResult, TriggerEvaluationResult, ActionExecutionResult.

Per-protocol config interfaces — ZigbeeConfig, ZWaveConfig, MatterConfig, WiFiDeviceConfig, BLEDeviceConfig, ThreadConfig — unified by the discriminated union ProtocolConfig.

Wellness / ergonomics: PressureMap, PressureCell, WeightDistribution, PostureAnalysis, SittingEvent, SittingDurationResult, SleepQualityResult, SleepSensorData, CircadianLightingResult, EnvironmentalComfortResult, ThermalComfortResult (simplified ASHRAE 55 PMV), AirQualityResult, HumidityComfortResult, NoiseComfortResult, WellnessReport.

Runtime Surfaces#

DeviceRegistry is an in-memory class (created via createDeviceRegistry factory). Methods:

registerDevice, deregisterDevice, getDevice, listDevices, getDeviceCount, updateDeviceFirmware, getFirmwareHistory, checkDeviceHealth, recordDeviceError, updateLastSeen, updateDeviceStatus, groupDevices, getGroup, listGroups, addDeviceToGroup, assignDeviceToRoom, getDevicesByRoom, setProtocolConfig, getProtocolConfig, getProtocolSummary, getDevicesNeedingAttention, clear.

Free functions: validateProtocol, validateProtocolConfig, assessSignalQuality, estimateBatteryDays, detectCapabilities.

SensorEngine (created via createSensorEngine) processes readings; supporting tables SENSOR_DEFAULT_UNITS, SENSOR_RANGES. Pure helpers include unit conversions (temperature, pressure across pa/hpa/psi/bar/atm/mmhg, light lux ↔ foot_candle), calculateLinearCalibration, applyCalibration, validateSensorReading, processSensorReading, calculateMovingAverage, calculateExponentialMovingAverage, calculateStats, detectAnomaly (z-score), fuseSensorData, evaluateThresholds.

AutomationEngine and SceneManager (created via createAutomationEngine, createSceneManager) evaluate rules and scenes. Pure helpers: sensorKey, evaluateTrigger, evaluateCompoundTriggers, evaluateCondition, evaluateConditions, evaluateRule, evaluateRules, executeAction (async), executeRuleActions (async).

Wellness functions: calculateWeightDistribution, calculateLeanAngle, analyzePosture, trackSittingDuration, assessSleepQuality, calculateCircadianLighting, assessThermalComfort, assessAirQuality, assessHumidityComfort, assessNoiseComfort, assessEnvironmentalComfort.

Sustainability Specifications (@seshat/sustainability)#

Domain Types#

LifeCycleStage (6: extraction, manufacturing, transport, use, maintenance, end_of_life). SystemBoundary (cradle_to_gate|cradle_to_grave|cradle_to_cradle). TransportMode (road|rail|sea|air). PowerSource (10 grid/source values).

MaterialCategory is a sustainability-local 20-value union that extends the common material categories with recycled variants: recycled_steel, recycled_aluminum, recycled_plastic.

ManufacturingProcess (19 processes). CarbonBreakdown (with sequestrationCredit). MaterialCarbonInput, TransportCarbonInput, ManufacturingCarbonInput. ProductDefinition. EndOfLifeScenario, DisposalMethod (8). ImpactCategory (8 ISO 14044 categories). StageImpact, LCAResult, ImprovementSuggestion. ProductComparison, StageComparison.

FastenerType (15). JointInfo. MaterialMarking (ISO 11469). CircularDesignScore (durability / repairability / recyclability / reusability / material-efficiency subscores). CircularityInput. RepairabilityInput (French repairability index inputs). DfDRecommendation.

WasteStream (12). WasteDiversionMethod (7). WasteEntry, WasteAudit, WasteStreamSummary. CertificationStatus. FSCClaimType (4). FSCChainOfCustodyRecord, FSCInput, FSCOutput. CertificationRecord. LEEDCreditCategory (7). LEEDCreditContribution. LEEDAssessment. SupplyChainEntry, MaterialSustainability, SustainabilityReport.

Functions & Tables#

• Carbon (carbon.ts): calculateMaterialCarbon, calculateTransportCarbon, calculateManufacturingCarbon, calculateEndOfLifeCarbon, calculateTotalCarbon, carbonRating, compareMaterialCarbon, calculateSupplyChainCarbon, carbonPaybackPeriod, describeMaterialCarbon. Tables/constants: MATERIAL_CARBON_FACTORS, WOOD_CARBON_SEQUESTRATION_PER_KG (1.84 kgCO₂/kg dry wood), SEQUESTRATION_ELIGIBLE, PARTIAL_SEQUESTRATION, TRANSPORT_EMISSION_FACTORS, DEFAULT_LOAD_FACTORS, PROCESS_POWER_KW, GRID_EMISSION_FACTORS, END_OF_LIFE_FACTORS.
• LCA (lifecycle.ts): performLCA, compareProducts, identifyHotspots, suggestImprovements.
• Circular design (circular-design.ts): assessCircularity, assessRepairability, designForDisassembly, quickCircularityScore.
• Certification (certification.ts): createCertificationRecord, trackCertification, isCertificationValid, daysUntilExpiry, filterCertificationsByStatus, getCertificationsExpiringSoon, validateChainOfCustody, determineMaxFSCClaim, assessLEEDContribution, assessMaterialSustainability, generateSustainabilityReport. Constants LEED_LEVELS, LEED_CATEGORY_MAX_POINTS, LEED_VOC_LIMITS.

Academy Specifications (@seshat/academy)#

Domain Types#

CraftDomain is a 16-value union identifying the major areas of craft practice: woodworking, joinery, wood_turning, wood_carving, furniture_making, cabinet_making, interior_design, spatial_harmony, finishing, upholstery, digital_fabrication, sustainability, restoration, timber_framing, marquetry, luthiery.

CraftSubSkill is a large union of named sub-skills grouped by domain. SkillProficiency, AssessmentRubric, AssessmentRubricCriterion, SkillAssessmentResult, StudentSkillProfile.

Curriculum: LessonContentType (10), LessonContent, AcademyLesson, AcademyCourse.

Learning paths: LearningGoal, LearningPathNode, PersonalizedLearningPath.

Certification: CertificationProgram, CertificationRecord, CertificationEligibility.

Mentorship: TeachingStyle (6), LearningStyle (5), CommunicationPreference (5), TimeSlot, MentorProfile, ApprenticeProfile, MentorMatch (8-dimension compatibility breakdown).

Knowledge base: TechniqueEntry.

Functions & Catalogs#

• Skill assessment (skill-assessment.ts): SKILL_LEVEL_THRESHOLDS, ASSESSMENT_RUBRICS; scoreToSkillLevel, skillLevelToScore, meetsSkillRequirement, calculateWeightedScore, executeAssessment, getSubSkillDomain, buildSkillProfile, assessmentResultToProficiency, identifySkillGaps.
• Learning paths (learning-path.ts): COURSE_CATALOG; compareSkillLevels, checkPrerequisites, resolvePrerequisiteChain, findCoursesForSkills, generateLearningPath, formatDomainName, formatSkillLevel, estimateProgressionHours, getPrerequisiteTree.
• Certification (certification.ts): CERTIFICATION_PROGRAMS; checkCertificationEligibility, issueCertification, isCertificationValid, getRenewalStatus, getCertificationPathForDomain, getAllCertificationPrograms.
• Mentorship (mentorship.ts): DEFAULT_MATCHING_WEIGHTS; per-dimension scorers (scoreSkillAlignment, scoreScheduleCompatibility, scoreCommunicationMatch, scoreStyleCompatibility, scoreDomainRelevance, scoreLogisticalFit, scoreAvailability, scoreReputation), scoreMentorMatch, findBestMentors, validatePairingViability.

Workshop Specifications (@seshat/workshop)#

Domain Types#

Branded IDs: WorkshopId, ZoneId, BookingId, IncidentId, CircuitId, MaintenanceId, DuctRunId.

Layout: WorkshopZoneType (13), FlooringType (7), WorkshopZone, MachineCategory (22), MachineClearance, MachinePlacement, WorkflowSequence, WorkshopLayout.

Inventory: ToolCondition (7), OwnershipStatus (4), ToolInventory, MaintenanceType (12), MaintenanceRecord, MaintenanceSchedule.

Materials: MaterialType (22), LumberDimensions, MaterialStock, MaterialUsageEntry, ReorderRecommendation, InventoryReport.

Safety: PPEType (10), FireSuppressionType (4), EmergencyEquipment, SafetySystem, IncidentSeverity (5), IncidentCategory (14), SafetyIncident, MachineSafetyBriefing, NoiseExposureResult.

Scheduling: BookingStatus (5), BookableResourceType (4), BookableResource, TimeSlot, BookingSlot, BookingConflict, ResourceUtilization.

Dust collection: DuctMaterial (4), DuctFitting (6), DuctSection, DuctRun, DustCollectionSystem.

Electrical: BreakerType (4), WireGauge (AWG literal union), ElectricalCircuit, ElectricalPanelSummary.

Layout-analysis results: ClearanceViolation, WorkflowAnalysis, LayoutAnalysis, SafetyComplianceResult.

Functions & Tables#

• Layout (layout.ts): tables MACHINE_CLEARANCES, MACHINE_CFM_REQUIREMENTS, MACHINE_DUST_PORT_INCHES, MACHINE_NOISE_LEVELS, MACHINE_AMPERAGE, COMMON_WORKFLOWS, FITTING_EQUIVALENT_LENGTH; functions getMachineClearanceEnvelope, validateClearances, analyzeWorkflow, designWorkshopLayout, calculateEquivalentLength, calculateStaticPressureLoss, calculateDustCollection, recommendWireGauge, calculateVoltageDrop, recommendBreakerType, calculateElectricalRequirements.
• Inventory (inventory.ts): in-memory tool and material stores — addTool, getTool, getAllTools, updateTool, removeTool, recordMaintenance, scheduleMaintenance, checkMaintenanceDue, getToolsByCondition, clearToolStore, trackMaterialStock, getMaterial, getAllMaterials, getMaterialsByType, deductMaterial, getMaterialUsageHistory, estimateReorderPoint, calculateBoardFeetFromDimensions, findLowStockMaterials, clearMaterialStore, generateInventoryReport.
• Safety (safety.ts): tables OSHA_NOISE_LIMITS, MACHINE_REQUIRED_PPE; functions maxPermissibleExposureHours, assessSafetyCompliance, reportIncident, getAllIncidents, getIncidentsBySeverity, getIncidentsInRange, clearIncidentStore, generateSafetyBriefing, calculateNoiseExposure.
• Scheduling (scheduling.ts): in-memory booking store — registerResource, getResource, getAllResources, createBooking, getBooking, cancelBooking, completeBooking, markNoShow, getBookingsForResource, getUpcomingBookings, checkAvailability, detectConflicts, calculateUtilization, clearSchedulingStore.

Persistence (@seshat/database)#

@seshat/database provides Zod row schemas plus a declarative migration system — it does not depend on Drizzle ORM, Knex, Prisma, or TimescaleDB at runtime. (The TODOS Phase 36 backlog lists "Prisma/Drizzle migrations" as planned work; the implemented library is a self-contained schema/migration description layer.)

Zod Row Schemas#

Each persisted entity has a UUID-validated branded ID schema, a full row schema, and an insert variant (which omits createdAt/updatedAt since the database generates those). The ProjectStatusSchema in the database layer is a different type from @seshat/core's ProjectPhaseSchema: ProjectStatusSchema is a six-value persistence status (draft, planning, in_progress, on_hold, completed, archived), while ProjectPhaseSchema is the eleven-phase lifecycle state machine. They are separate concepts.

ID schemas: ProjectIdSchema, MaterialIdSchema, ToolIdSchema, DeviceIdSchema, RoomIdSchema, FloorIdSchema, BuildingIdSchema, UserIdSchema, CourseIdSchema, LessonIdSchema, AutomationIdSchema, WorkshopIdSchema, DesignIdSchema.

Row schemas (each yielding a *Row inferred type and *InsertSchema variant): WoodSpeciesSchema, MaterialSchema, ToolSchema (with CNC-specific optional columns), RoomSchema, SmartDeviceSchema, SensorReadingSchema, AutomationRuleSchema, ProjectSchema, CourseSchema, LessonSchema, WorkshopSchema, DesignSchema, BuildingSchema, FloorSchema, StudentProgressSchema, FengShuiAnalysisSchema, VastuAnalysisSchema, SustainabilityAssessmentSchema.

Supporting object schemas: DoorOpeningSchema, WindowOpeningSchema, CutListSchema, BillOfMaterialsSchema, ColorPaletteSchema, MoodBoardItemSchema, DesignBriefSchema, CarbonFootprintSchema, and the Feng Shui / Vastu nested schemas.

Migration Definitions#

migrations.ts defines a Knex-compatible description layer (not a Knex dependency): types ColumnType, ColumnDefinition, ForeignKeyDefinition, IndexDefinition, TableDefinition, MigrationDefinition.

migration001_initial creates 18 tables: buildings, floors, rooms, wood_species, materials, tools, smart_devices, sensor_readings, automation_rules, projects, courses, lessons, student_progress, workshops, designs, feng_shui_analyses, vastu_analyses, sustainability_assessments — with columns, foreign keys, and indexes fully specified.

ALL_MIGRATIONS is the ordered migration list; TABLE_NAMES and TABLE_COUNT are derived; getTableDefinition(name) looks one up. generateMigrationSQL(migration) produces CREATE TABLE / ALTER TABLE … ADD CONSTRAINT / CREATE INDEX SQL strings — it does not execute anything.

Seed Data#

seed.ts ships curated reference data for development and testing:

• ROOM_TYPES — 26 room-type info records with typical dimensions, ideal lighting, Feng Shui element, and Vastu direction.
• WOOD_SPECIES_SEEDS — 25 wood species typed as z.input<WoodSpeciesInsertSchema>.
• TOOL_SEEDS — 20 real woodworking tools.

Validation Rules (Summary)#

These rules are enforced at the Zod schema boundary. Violations throw Zod ZodErrors that the application layer must handle.

• Project: name 1–255 chars, description ≤2000, IDs must be UUIDs, budget amounts non-negative integer cents, currency exactly 3 chars.
• Workflow: step dependsOn references must resolve; cycles are rejected by topologicalSort; step transitions confined to VALID_STEP_TRANSITIONS; phase transitions confined to VALID_TRANSITIONS.
• Database rows: wood-species jankaHardness 0–5500 lbf, density ≤1.5 g/cm³, shrinkage 0–20% (tangential) / 0–15% (radial); ratings constrained to 1–10; hex colours validated by regex; scores constrained 0–100; budget min ≥0 and max >0.
• Sensors: validateSensorReading checks values against SENSOR_RANGES; anomaly detection uses a configurable z-score threshold.

Acceptance Criteria#

• Each of the 11 libraries builds with npx tsc --noEmit and ships a Vitest suite (*.test.ts). Test suites are substantial — for example @seshat/common has 231 it() cases, @seshat/database 202, @seshat/smart 188.
• Domain computations are deterministic pure functions; in-memory stores (ProjectManager, DeviceRegistry, workshop inventory/scheduling stores) expose clear/clearStore helpers for test isolation.
• All numeric reference data (wood properties, joint strengths, carbon factors, protocol specs) is sourced from real-world references, not random or placeholder values.

Out of Scope (Not Implemented)#

The following appear in product narrative or the Phase 36 backlog but have no implementation in libs/seshat/:

• HTTP/REST API gateway, controllers, or routes.
• A domain event bus — SeshatEventType / SeshatEvent are bare type declarations with no publisher or transport.
• AI image generation (Stable Diffusion, ControlNet, depth estimation) — the design library produces structured data, not rendered images.
• An ORM-backed runtime database, TimescaleDB hypertables, or pgvector semantic search — persistence is Zod schemas plus declarative migration descriptions.
• A live MQTT broker connection — SmartConfig.mqttBrokerUrl is a config field and SMART_DWELLING_MQTT a feature flag, but no MQTT client is implemented.
• Digital-twin runtime — the DigitalTwin types are declared but unused.