ELog Rebuild Blueprint

ELog rebuild validation notes for the standalone vyuh_blueprint repository.

ELog is the first serious proving ground for Entity Blueprint.

The goal is not to create a simplified demo. The goal is to rebuild the real ELog surface from blueprint definitions, then use the gaps to harden the entire Vyuh Blueprint stack. In that model, entities are composition boundaries and facets own actions, lifecycle, policies, evidence, audit, and projection.

If Blueprint can express ELog, it is much closer to being ready for CVS, WMS, IPQC, BRM, batch manufacturing, transport, and other regulated manufacturing solutions.

Source System Inventory

The current ELog implementation spans DB schema, server routes, entity-system UI configuration, operational workflows, policies, analytics, realtime events, and regulated audit/evidence surfaces.

DB Slices

The current Supabase/Postgres schema is organized into these ELog slices:

Slice	Current responsibility	Blueprint treatment
Access	Role categories, roles, permissions, operations, user groups, memberships, user roles.	IAM module plus ELog grants and assignments.
Entity masters	Areas, equipment, area/equipment categories, area-equipment links, area adjacency, business associates, equipment parts.	Manufacturing core entities plus ELog descriptors and audited join entities.
Checklist	Checklist templates, checklist usages, usage instructions, checklist submission functions.	Checklist entities, execution operations, evidence, lifecycle, and workflow hooks.
Log	Log templates, log usages, report templates, report generations, log events.	Logbook entities, usage transactions, report operations, event evidence.
Resource	Resource policies, usages, grants, problems, flags, resource states, availability functions.	Resource operation module with scoped policy resolution, resource usage lifecycle, exceptions, remedies, and policy gates.
Workflow	Workflow definitions, instances, user tasks, events, inbox functions, admin stats.	Workflow runtime module with operation-linked lifecycle transitions.
Product	Units of measure, products, batches, cleaning types, product cleaning requirements.	Manufacturing product/material/batch entities plus ELog and CVS facets.
Inbox	User scope and inbox badge functions.	IAM plus workflow task and activity assignment projections.
Dashboard	Dashboard configs, role dashboards, notifications.	UI/app module, saved surfaces, role-scoped dashboard grants.
Common	Cross-schema views, saved views, RLS policies, e-signatures, analytics functions, performance indexes.	Runtime/common modules for audit, evidence, projections, search, and performance hints.
Events	Events table, realtime indexes, event reactor state, resource event functions.	Event stream module, outbox subscriptions, realtime projections.
Activity	Activities, activity artifacts, linked activities, compliance, scheduling, submission, state machine, artifact rules, resource sync.	Central operational transaction aggregate.
Cron	Lifecycle cron config.	Scheduled operation module and runtime job descriptors.
Holiday	Holiday calendars and entries.	Calendar module used by scheduling and due-date policies.
Presets	Industry presets, preset areas/equipment/checklists/log templates/policies/dashboards/roles/schedules.	Seed/onboarding module with scenario packs.
Manufacturing	Campaigns, batch lifecycle, batch gate, resource usage manufacturing extensions.	Manufacturing operations module layered on product/batch/resource usage.
Punches and dies	Tooling types, punch sets, module config, code generation, equipment part versioning.	Tooling module layered on manufacturing equipment and equipment parts.
Search	Trigram indexes and global search functions.	Search projection and DB hints generated from field/query metadata.

DB Tables and Entity Candidates

The current schema exposes these major table-backed concepts:

Area	Tables	Blueprint model
IAM	role_categories, roles, role_permissions, operations, user_groups, user_group_members, user_roles	iam.role_category, iam.role, iam.permission_grant, iam.action, iam.user_group, iam.membership, iam.role_assignment
Manufacturing masters	areas, area_categories, equipments, equipment_categories, equipment_parts, area_equipment, area_user_groups, equipment_user_groups, area_adjacency, business_associates	manufacturing.area, manufacturing.equipment, manufacturing.equipment_part, audited relationship entities and assignment facets
Product and batch	unit_of_measures, products, batches, cleaning_types, product_cleaning_requirements	manufacturing.unit_of_measure, manufacturing.product, manufacturing.batch, CVS/ELog cleaning facets
Resource operations	resource_policies, resource_usages, resource_states, resource_flags, resource_flag_types, problems, problem_types	Resource policy, usage transaction, state projection, exception/remedy, active flag models
Activity	activities, activity_artifacts	Activity aggregate, evidence/artifact facet, scheduling facet, lifecycle facet
Checklist	checklist_templates, checklist_usages, checklist_usage_instructions	Checklist template, execution instance, instruction response facets
Log	log_templates, log_usages, log_events, report_templates, log_report_generations	Log template, log usage, log event, report template, report generation
Workflow	workflows, workflow_instances, workflow_user_tasks, workflow_events	Workflow definition, instance, task, event
Dashboard and view config	dashboard_configs, role_dashboards, saved_views, notifications	Dashboard config, role dashboard assignment, saved view, notification
Events and analytics	events, event_reactor_state, resource_activity_daily_rollups	Event stream, reactor checkpoint, analytics rollup
Scheduling and calendar	lifecycle_cron_config, holiday_calendars, holiday_entries	Scheduled operation config, calendar, calendar entry
Onboarding and presets	preset_*, onboarding_status, preset_schedules	Seed pack, onboarding session/status, preset scenario models
Manufacturing operations	campaigns plus batch/resource usage extensions	Campaign, batch lifecycle, production gates
Tooling	pd_module_config, tooling_types, punch_sets	Tooling config, tooling type, punch set

Many relationship tables should not be treated as invisible DB plumbing. In a regulated system, joins are often auditable assignments:

• area_equipment
• area_user_groups
• equipment_user_groups
• area_adjacency
• user_group_members
• user_roles
• role_permissions
• role_dashboards
• linked_activities

Blueprint should model these either as relationship facets with audited join storage or as explicit relationship entities when they have state, lifecycle, audit, policy, or effective-date semantics.

API Route Families

The current ELog API has route families for:

• activities
• areas
• batches
• campaigns
• checklists
• drafts
• entity checks
• entity lifecycle
• equipment
• health
• holiday calendars
• lifecycle proxy
• log reports
• log usages
• my workspace
• onboarding
• operations
• permissions
• problems
• resource flags
• resource policies
• resource usages
• resources
• roles
• saved views
• search
• system jobs
• workflows

This proves that Blueprint needs first-class API conventions. DB and UI hints are not enough, but most API behavior should still be derived automatically from entity, facet, operation, projection, and policy names.

What Blueprint Can Express Today

The current Blueprint model can already express a meaningful portion of ELog:

• modules and module dependencies
• base manufacturing entities
• ELog descriptors layered on manufacturing entities
• facets with fields, relationships, lifecycle, actions, rules, conditions, evidence, audit, derived values, and state projection
• DB hints on modules, entities, and fields
• UI hints on modules, entities, facets, fields, and actions
• seed hints for demo and validation data
• bootstrapped entity assembly
• origin graph lineage
• Postgres identity tables, facet tables, audit tables, version tables, indexes, generated columns, and joined read views
• basic OpenAPI generation from entity CRUD and facet actions

This is enough to start rebuilding ELog manually and imperatively.

What Must Be Hardened

ELog exposes the missing parts clearly.

API Conventions and Overrides

The normal API surface should be generated by convention. A blueprint author should not have to manually describe common CRUD routes, action transaction routes, response envelopes, error envelopes, pagination, filtering, sorting, search, audit links, evidence links, or action-context capture.

The framework should derive:

Source	Generated API behavior
Module(name: 'elog')	OpenAPI tag group, route namespace, default auth posture, schema prefix.
Entity(name: 'activity')	Collection route, detail route, standard list/detail response envelopes, entity OpenAPI schema.
Facet(name: 'lifecycle')	Facet projection fields, facet-scoped read/write schemas, nested route naming where needed.
ActionDefinition(name: 'submit')	Facet action transaction route, request payload schema, action-context requirement, audit/evidence envelope, policy-gate checks.
Lifecycle transitions	Transition action routes when no custom action is declared.
FacetProjection	List/detail/search/filter/sort fields and query parameters.
PolicyGate	OpenAPI extensions, authorization checks, disabled/action-state reason payloads.
Evidence and AuditEnvelope	Standard evidence/signature/reason links in request and response envelopes.

API hints should be optional overrides, not the primary authoring path.

Optional API metadata is still useful at module, entity, facet, action, and projection levels:

Model	Required API hint
Module	API base path, OpenAPI tags, versioning, auth posture, exposed/private schema posture.
Entity	CRUD exposure, route name, list/detail shapes, pagination, search, sort, filters, response envelopes.
Facet	Facet route exposure, nested resources, read/write projection shape.
ActionDefinition	HTTP method/path, request schema, response schema, action context requirement, idempotency, evidence capture, policy gates, error contract.
DerivedValue / FacetProjection	Query route, cache posture, realtime posture, OpenAPI response shape.

These hints should mostly say "hide", "rename", "custom route", "streaming", "private", "different cache posture", "custom response", or "custom runtime handler". They should not be needed for the common case.

The API compiler must compile bootstrapped entities, not raw module entities. Otherwise descriptor-contributed ELog facet actions disappear from OpenAPI.

DB Generation

The DB compiler needs to grow from DDL emission into migration planning:

• RLS policy generation
• grants for exposed schemas
• private schema functions
• security-invoker views for exposed read models
• audit and evidence tables
• join-table audit
• assignment tables with effective dates and policy scope
• generated foreign keys for typed and polymorphic resources
• indexes from query patterns
• search projections
• analytics rollups
• realtime publication/outbox setup
• migration diff and artifact fingerprints for incremental compilation

Runtime Contracts

ELog needs runtime contracts for:

• IAM principal resolution
• role/group/user assignment inheritance
• effective policy resolution
• resource policy snapshots
• activity lifecycle execution
• checklist execution
• log event capture
• workflow task execution
• evidence capture
• e-signature capture
• audit event write
• exception/remedy handling
• realtime operational stream

Entity System UI Generation

ELog also proves that generated UI cannot stop at forms and tables. It needs:

• route builders per entity
• workspace navigation
• master-detail pages
• execution dialogs
• checklist execution panes
• activity boards
• resource status panels
• policy editors
• workflow/inbox pages
• audit/evidence viewers
• analytics dashboards
• saved views
• field/action visibility from grants and policy gates

The UI compiler should generate Entity System configuration first, then allow hand-authored specialized widgets where the blueprint marks a surface as custom.

ELog Blueprint Modules

The rebuild should not be one giant elog module. It should be a set of composable modules.

Module	Purpose	Examples
mfg.core	Shared manufacturing masters.	Product, batch, area, equipment, equipment part, material, method.
mfg.iam	Common regulated identity and authorization.	Users, groups, roles, permissions, actions, grants, assignments, delegations, reviews.
elog.resource	Resource availability and policy world model.	Resource policies, usages, states, flags, problems, clear/release operations.
elog.activity	Central operational work model.	Activity, activity artifact, linked activity, scheduling, submission, review.
elog.checklist	Checklist authoring and execution.	Checklist template, usage, instruction response, timers, submit/approve.
elog.logbook	Electronic logbook templates and usage.	Log template, log usage, log event, reports.
elog.workflow	Workflow runtime declarations and task surface.	Definition, instance, user task, workflow event.
elog.dashboard	Dashboards, saved views, notifications.	Dashboard config, role dashboard, saved view, notification.
elog.calendar	Operational calendars and schedules.	Holiday calendar, entries, lifecycle cron config.
elog.presets	Demo/onboarding seed packs.	Preset industries, areas, equipment, policies, roles, schedules.
elog.events	Operational event stream and reactors.	Event, reactor checkpoint, resource event projections.
elog.analytics	Read models and rollups.	Resource activity daily rollups, health summaries, operational status maps.
elog.manufacturing	Batch/campaign operations.	Campaigns, batch lifecycle, batch gates.
elog.tooling	Punches and dies/tooling.	Module config, tooling types, punch sets.
elog.search	Global search and query projections.	Trigram fields, global search read model.

Each module contributes entities and descriptors. Shared manufacturing masters remain in mfg.core; ELog adds operational facets to them.

Facet Model for ELog

The ELog rebuild should converge on a small set of recurring facets:

Facet	Meaning
identity	Code, title/name, description, active status, display metadata.
tenancy	Tenant/site scoping and isolation.
governance	Versioning, approval, audit, signature, reason, retention, review posture.
assignment	Assigned users, groups, roles, resource scopes, effective dates.
lifecycle	State machine and transitions for operational work.
resource_scope	Area/equipment/product/batch/campaign scope.
policy_snapshot	Frozen effective policy/config at transaction start.
execution	Runtime execution data and timestamps.
evidence	Artifacts, logs, photos, checklist responses, signatures, instrument data.
exception	Problems, flags, deviations, remedies, clear/release actions.
analytics	Rollups, counts, status maps, health summaries, performance projections.
search	Search label, tags, trigram/query fields, global search projection.

Facets own their state projection and behavior. The effective entity state is the union of those projections. Actions that feel entity-wide, such as publish, archive, restore, and purge, belong to the identity facet.

Critical ELog Aggregates

Activity

activity is the central transaction aggregate.

It needs facets for:

• identity: name, description, type
• resource scope: resource type/id, operating area
• assignment: assigned user/group, assigned by
• lifecycle: scheduled, assigned, in progress, paused, submitted, under review, approved, revision requested, rejected, completed, cancelled
• evidence: operator signature, witness signature, artifacts
• scheduling: origin, schedule ref, scheduled/due timestamps
• policy snapshot: frozen activity config from effective resource policy
• workflow: workflow instance and task links
• audit: created/updated/submitted/completed actors and timestamps

Operations include:

• create activity
• assign
• start
• pause/resume
• save log
• submit
• decide review
• cancel
• link activity
• get timeline
• get artifacts
• validate submission

Resource Usage

resource_usage is the active session between a user and an area/equipment resource.

Facets:

• resource scope
• lifecycle: active, paused, completed, cancelled
• production context: product, batch, campaign
• actor context: started by, stopped by
• policy snapshot
• audit

Operations:

• start usage
• stop usage
• pause/resume
• release resource
• check availability
• compute operational status

Checklist Usage

checklist_usage is an execution instance of a checklist template.

Facets:

• template snapshot
• instruction responses
• timers
• workflow state
• reviewer/witness assignment
• evidence
• audit

Operations:

• start usage
• save instruction response
• submit instruction response
• complete instruction
• decide instruction
• start timer
• submit checklist

Log Usage and Log Events

log_usage is a running logbook session. log_event is the append-only event record.

Facets:

• template snapshot
• resource scope
• lock state
• event stream
• report generation
• evidence
• audit

Operations:

• create event
• list events
• lock log usage
• generate report
• generate template PDF

Resource Policy

resource_policy is the scoped world model for how resources are allowed to be used.

Facets:

• scope: tenant/site/area/equipment/category/type
• domain configs: cleaning, calibration, maintenance, usage, inspection
• merge/inheritance: parent policies and conflict posture
• effective policy projection
• lifecycle/governance
• audit

Operations:

• evaluate policy
• stream evaluate
• clone
• resolve effective policy
• show inheritance chain
• detect scope conflict
• update governance

Projections in ELog

ELog has several projection families that Blueprint should generate or declare:

Projection	Source
area_list_projection	Area identity, hierarchy, category, usage counts, status.
equipment_list_projection	Equipment identity, category/type, area, operational status, flags.
activity_list_projection	Activity lifecycle, assignment, due dates, resource scope, workflow state.
resource_production_state	Active resource usage plus product/batch/campaign context.
resource_health_summary	Resource state, flags, usage, exceptions, stale policy state.
entity_global_search	Search across masters, activities, workflows, reports, dashboards.
resource_activity_daily_rollups	Analytics rollup by resource and day.
my_inbox	Workflow tasks, activities, approvals, overdue items for current actor.

Projection metadata must drive:

• SQL views or materialized views
• indexes
• API list/query endpoints
• UI list columns and filters
• realtime subscriptions
• analytics panels

Compiler Milestones

Milestone 1: Artifact Generation

Create an ELog blueprint package in vyuh_mfg that compiles:

• manufacturing + iam + elog
• elog.postgres.sql
• elog.openapi.json
• elog.db-plan.txt
• elog.api-plan.txt
• elog.ui-plan.txt
• elog.seed-plan.txt

This proves we can inspect the generated surfaces without applying them to a database yet.

Milestone 2: API Convention Engine and Bootstrapped API Compilation

Add the standard API convention engine and update ApiCompiler to use blueprint.bootstrap().assembledEntities.

The compiler should derive the common API surface automatically:

• GET /<module>/<entity> list
• POST /<module>/<entity> spawn/create
• GET /<module>/<entity>/{id} detail
• PATCH /<module>/<entity>/{id} update when allowed
• POST /<module>/<entity>/{id}/facets/<facet>/actions/<action> regulated facet action transaction
• facet projection routes when the facet declares a separate projection
• relationship routes for assignments and audited joins
• standard response envelopes, error envelopes, evidence links, audit links, pagination, filtering, sorting, and search

API hints should then refine or override the generated defaults.

The generated OpenAPI must include descriptor-contributed facet actions such as:

• equipment resource operations
• area activity operations
• product usage operations
• activity lifecycle operations
• checklist execution operations
• resource policy evaluation operations

Milestone 3: ELog Master Model

Model ELog masters and assignments:

• areas, equipment, categories, equipment parts
• products, batches, units, cleaning types
• user groups, roles, permissions, operations, grants
• log templates, checklist templates, report templates
• dashboards, saved views, holiday calendars
• audited join tables and assignment relationships

Milestone 4: ELog Transaction Model

Model high-volume transactions as facet-owned actions:

• activity
• resource usage
• checklist usage
• log usage
• workflow instance/user task
• events
• problems/flags
• report generation

Milestone 5: Generated Supabase Baseline

Generate a fresh Supabase schema from the ELog blueprint and compare it to the current ELog schema:

• tables
• columns
• joins
• indexes
• RLS policies
• views
• functions
• triggers
• audit/versioning
• grants

The comparison should produce a compiler gap report.

Milestone 6: Runtime Smoke Path

Mount the generated API against Vyuh Server and Supabase:

• authenticate actor
• resolve IAM grants
• create an activity
• start resource usage
• execute a checklist instruction
• submit activity
• write audit/evidence
• emit event/outbox row
• query generated projections

Incremental Compilation

ELog is too large for whole-world regeneration on every change.

The compiler stack needs artifact fingerprints:

blueprint path -> compiler dependencies -> generated artifact

Examples:

• Changing activity.lifecycle.status invalidates activity DDL, OpenAPI action schemas, UI lifecycle actions, seed scenarios, and workflow tests.
• Changing equipment.physical_profile.area_id invalidates equipment table DDL, list projection, resource policy joins, area/equipment relationship UI, and search indexes.
• Changing resource_policy.effective_policy_projection invalidates policy API routes, generated SQL views/functions, action gates, and UI affordances.

The origin graph already gives the blueprint lineage. The next step is a compiler dependency graph and per-artifact hashes.

Recommendation

Use ELog as the blueprint hardening track.

Do not attempt a one-shot rewrite. Instead:

1. Preserve the current ELog repo as the source-of-truth behavior oracle.
2. Recreate ELog in vyuh_mfg as imperative blueprint definitions.
3. Generate DB/API/UI/seed artifacts from the blueprint.
4. Diff generated artifacts against current ELog DB/API/UI behavior.
5. Fix blueprint vocabulary and compilers wherever ELog cannot be expressed.
6. Only then use the hardened stack for CVS and broader manufacturing apps.

This gives us a real manufacturing benchmark without pretending the current compiler surface is complete.