wyuc 90f5f3942b
fix(release): dedupe the published dsl, close two release-path blind spots (#1019)
* fix(release): dedupe the published dsl, close two release-path blind spots

Three independent defects on the release path.

1. `@openmaic/storage`, `@openmaic/renderer` and `@openmaic/importer`
   declared `"@openmaic/dsl": "workspace:*"`, which pnpm publishes as an
   EXACT pin. The tarballs on the registry today say storage@0.1.1 needs
   dsl 0.5.0, renderer@0.0.3 needs dsl 0.4.0 and importer@0.1.1 needs dsl
   0.4.0, so installing storage together with renderer yields two copies
   of the dsl. The dsl carries the schema, the validators and the version
   constants, so a document produced against one copy can be validated by
   the other's schema revision.

   `workspace:^` publishes as `^0.5.0`. Under 0.x that admits 0.5.x, so a
   dsl patch reaches dependents without republishing them while a dsl
   minor still requires a deliberate dependent release. All three
   packages take a patch version increase, both because
   check-package-version-bumps.mjs requires one and because the corrected
   range only reaches consumers through a new release.

   The tarball smoke test now asserts the packed range, so an exact pin
   cannot come back unnoticed.

2. The publish workflow's build-integrity guard ran `git diff --quiet --
   packages/@openmaic`, which compares the worktree to the INDEX. The
   steps before it run third-party package code, which needs no
   credential to rewrite a tracked file and `git add` it, after which the
   guard reported clean and the rewritten bytes were packed and
   published. Both copies of the guard now compare against HEAD, the
   commit actually being released.

3. `@openmaic/storage`'s PostgreSQL contract suites refuse to skip when
   STORAGE_PG_CONTRACT_REQUIRED=1, but that refusal is a `throw` inside
   the test modules, so it never fires if vitest stops collecting them.
   Collection is decided by `packages/@openmaic/storage/vitest.config.ts`,
   which is on the ignore list of publishable inputs, so excluding
   `*.pg.test.ts` there turns both PostgreSQL backends off with a green
   run and no version bump.

   scripts/assert-pg-contract-suites.mjs reads vitest's json results and
   requires both suite files to be present, passed and non-empty, keyed
   on the file names rather than on a count. It runs in the publish
   workflow's validate job and in the storage PostgreSQL contract
   workflow.

Merging this publishes @openmaic/storage@0.1.2, @openmaic/renderer@0.0.4
and @openmaic/importer@0.1.2. That republish is the fix for (1), not a
side effect of it: the corrected dependency range exists only in a
tarball that has not been cut yet.

* fix(release): audit the contract database, pin the format version to a minor

Follow-up on cross-vendor review of the three release-path fixes.

1. The PostgreSQL assertion proved far less than it claimed. Vitest's
   `assertionResults` are test CASES, not `expect()` calls, so one
   `test('x', () => {})` per required filename satisfied it — and the
   whole surface is reachable without a version bump, because `test/` is
   on the same ignore list as `vitest.config.ts`. A `vi.mock('pg', ...)`
   in the already-wired `test/setup.ts`, or a stubbed suite body, made it
   print "ran against a real database" having checked nothing of the
   sort.

   The script now runs in two phases. Phase 1 keeps the file/status
   checks. Phase 2 connects to PG_CONTRACT_URL from outside the vitest
   process and requires all five tables the two backends own to exist and
   to show inserts in pg_stat_user_tables. Nothing inside `test/` can
   forge that. Cumulative insert counters rather than surviving rows,
   because the suites clean up after themselves. The success message now
   states only what was checked.

2. Validation packed with lifecycle scripts while publishing runs
   `--ignore-scripts`, so committing `workspace:*` plus a `prepack` that
   rewrites it to `workspace:^` passed the tarball assertion and then
   published the exact pin. Both the smoke test and the workflow's
   dry-run pack now pass `--config.ignore-scripts=true`, so validation
   and publication have identical lifecycle semantics.

3. `workspace:^` unpins the serialized-format version that the exact pin
   was silently holding. DSL_VERSION and RUNTIME_DSL_VERSION are
   decoupled from the npm version by design, and storage compares them by
   value across the package boundary. Under `^0.5.0` a dsl PATCH could
   therefore hand a new format to an already-published storage: one
   install resolves it and stamps the new version into document_stages,
   another install pinned to the older patch reads that row and hard-
   fails. Two installs of one published storage version, data-
   incompatible.

   check-package-version-bumps.mjs now requires a change to either
   constant to carry at least a MINOR increase of the dsl package
   version, since a caret does not cross a 0.x minor. The rule is
   documented next to both constants. That doc edit is itself a
   publishable change, so dsl takes a patch bump to 0.5.1.

4. The range and build-integrity guards ran only in the publish workflow,
   so a pull request restoring `workspace:*` or leaving a stale generated
   file failed at release time, after a version number had been spent.
   ci.yml gains a cheap source-level range check
   (scripts/check-internal-dependency-ranges.mjs) and the
   `git diff --quiet HEAD` integrity check after its install step. The
   tarball assertion stays where it is as the release-time proof of
   actual published behaviour.

Merging this now publishes @openmaic/dsl@0.5.1 as well as
@openmaic/storage@0.1.2, @openmaic/renderer@0.0.4 and
@openmaic/importer@0.1.2.

* fix(release): fail the gates closed, and state what they actually prove

Confirmation round on the release-path fixes.

1. The format-version rule failed open if version.ts moved. It hard-coded
   one source path and returned successfully when either revision lacked
   it, so renaming the file, changing DSL_VERSION and bumping dsl by a
   patch passed both checks. It now reports an error whenever the file is
   absent at either revision while dsl has any publishable change. The
   constant regex is anchored to the start of a line, so a commented-out
   declaration cannot be read as the value, and a duplicate declaration is
   an error rather than a coin flip.

2. "At least a MINOR" was wrong past 1.0.0: `^1.0.0` admits minors, so a
   format change shipped as a minor would float into published dependents
   exactly as the rule exists to prevent. The rule is now stated as what
   it needs to be — an increase the dependents' caret range will NOT admit
   — computed from the pre-change version: a minor while dsl is 0.x, a
   major once it reaches 1.0.0. The error message and the docs in
   version.ts say the same thing.

3. Internal declarations outside `dependencies` bypassed both range
   checks. Keeping `dependencies` at `workspace:^` while adding an exact
   `peerDependencies` or `optionalDependencies` entry published a second,
   tighter constraint and passed. An owned package must now appear exactly
   once, in `dependencies`; entries in the peer and optional fields are
   rejected outright, in the source check and in the packed-manifest
   assertion. The global count test is replaced by naming the three
   dependents that must be present.

4. The format rule compared against the base tip, so an un-rebased branch
   produced an inverted message. It now uses the merge base, matching the
   `base...HEAD` form the rest of diff mode uses. Deliberately not applied
   to the version comparison, where the tip is the correct reference.

5. Phase 2 had no baseline, so cumulative counters from an earlier run
   satisfied it forever against a non-ephemeral database. It now captures
   the counters before the vitest step and requires a positive delta.
   Both workflows gained the capture step.

6. Phase 2 overclaimed. It proves rows were inserted into those five
   tables during the run, not that the built PgDocumentStore and
   PgRuntimeStore inserted them — `test/` is on the publishable-input
   ignore list, so test code could write directly. The success message now
   says exactly that, and the script documents the threat model: this
   catches accidental silencing, which is the defect it was written for;
   it is not a defence against someone who can merge changes to `test/`,
   who can alter production code just as easily.

Also: scripts/openmaic-packages.mjs is now the single source for the
owned package list, consumed by all three checking scripts, and it
cross-checks itself against both the packages directory and
publish-packages.yml so a package added in one place and forgotten in
another fails rather than going quietly exempt. The workflow's own YAML
lists cannot import it, which is why they are cross-checked instead.

* fix(release): let the format-version source move without opening the gate

Failing closed on a missing version.ts is right, but on its own it made a
rename impossible to merge: the new path does not exist at the base
revision either, so the check refused both before and after the move.

DSL_VERSION_SOURCES is now an ordered candidate list, resolved per
revision against the first path that exists there. A rename lands by
prepending the new path in the same change, and the comparison still
happens across the move. Absent everywhere at either revision, while dsl
has any publishable change, remains an error.

* fix(release): report package-list drift instead of crashing on it

Every check in check-internal-dependency-ranges.mjs reads the shared
package list, so a list naming a package that does not exist threw an
ENOENT out of readManifest before any finding was printed. It failed
closed, but unreadably. The list is now validated first and fatally, with
its own headline.

* fix(release): anchor the caret to the base branch, and check the gates' own inputs

Final confirmation round.

1. The caret escape was computed from the merge base, which is the wrong
   reference for it. With merge base dsl 0.5.1, an ordinary minor landing
   on main taking the tip to 0.6.0, and HEAD at 0.6.1 with a changed
   DSL_VERSION, the rule computed the escape from 0.5.1, got 0.6.0, and
   accepted 0.6.1 — but dependents released against 0.6.0 publish
   `^0.6.0`, which admits 0.6.1, so the new format reached them anyway.
   0.6.1 is also the minimum the ordinary version check allows, making
   that the default outcome rather than an unlucky one.

   The escape is now computed from the HIGHEST dsl version reachable on
   the base branch. Whether the format moved still comes from the merge
   base, because that is a question about the branch. The comment on
   mergeBaseWithHead now records that it is a no-op in both current CI
   invocations (checkout uses the merge ref on pull_request, and the
   before-SHA is an ancestor on push) rather than claiming a case that is
   not exercised there.

2. The workflow cross-check matched raw text, so a commented-out trigger
   path still satisfied it while silently disabling that package's
   release. Full-line comments are now stripped first; the `on.push.paths`
   list and every `for pkg in ...` loop are compared as exact sets, so an
   unexpected entry fails as well as a missing one; and `--filter` usage
   is checked more loosely, because individual steps legitimately filter
   subsets. The limits of a textual check are stated where it lives.

3. `locate()` returned the first candidate format-version source that
   existed, so during a half-finished rename the gate could compare a file
   that is no longer the exported one. It now resolves every candidate per
   revision and fails unless exactly one declares the constants.

4. INTERNAL_DEPENDENTS was checked in one direction only, so deleting an
   entry exempted that package from the source check and from the packed
   assertion that iterates the same map. It is now cross-checked both
   ways, an owned package in another owned package's devDependencies is
   rejected outright, and multiple owned dependencies no longer collapse
   to whichever was declared last.

5. assertPackageListIsComplete() now also runs in release mode, which is
   the gate that decides what gets published; and the PostgreSQL script
   consumes flag values properly instead of treating the first non-flag
   argument as the results path.

Also documents, in openmaic-packages.mjs, the threat model these gates
share: they catch mistakes, and anyone who can merge edits to scripts/
can edit production code directly, so deliberate subversion is out of
scope and cannot be closed by adding further checks.
2026-08-02 22:44:34 -04:00
..

@openmaic/dsl

The contract keystone of the MAIC SDK family. @openmaic/dsl is pure spec — the slide object-model types, build-time JSON Schema artifacts, pure validators / type-guards, and version/migration helpers — with zero runtime dependencies (no React, no pptx, no echarts).

That purity is the whole point: the renderer, the importer, and any future package can depend on @openmaic/dsl without pulling in junk.

Dependency arrows (acyclic)

@openmaic/dsl       ->  (nothing)
@openmaic/renderer  ->  @openmaic/dsl
@openmaic/importer  ->  @openmaic/dsl
@openmaic/exporter  ->  @openmaic/dsl     (reserved, future)

@openmaic/dsl is the only package everything else depends on, and it depends on nothing.

What's in here

Module Contents
slides.ts The slide object model: Slide, PPTElement and all variants, theme, background, animation, table/chart/code types, plus ElementTypes / ShapePathFormulasKeys enums.
stage.ts The lesson skeleton: Stage, generic Scene<TAction, TContent>, SceneType, StageMode, Whiteboard, VideoManifest, SlideContent, QuizContent, MultiAgentConfig, GeneratedAgentConfig, plus isSlideContent / isQuizContent guards.
action.ts The playback verb set: Action and all variants (spotlight, laser, speech, the Wb* whiteboard family, play_video, discussion, and the widget_* interaction actions), ActionType, the frozen ACTION_TYPES set + isActionType guard, the FIRE_AND_FORGET_ACTIONS / SLIDE_ONLY_ACTIONS / SYNC_ACTIONS category lists, plus the PercentageGeometry overlay type.
guards.ts Pure discriminant type-guards (isTextElement, …) and PPT_ELEMENT_TYPES.
validate.ts Pure, zero-dep structural validators — validateStage / validateScene / validateAction returning an error-collecting ValidationResult.
normalize.ts Pure, zero-dep defaulters — normalizeElement / normalizeSlide / normalizeScene / normalizeStage and the canonical ELEMENT_DEFAULTS. Fills required-field defaults, derives geometry, fails loud on malformed input; the repair counterpart to validate*. normalizeSlideWith({ onInvalid: 'drop', onDropped }) builds a map-safe normalizeSlide variant so producers normalizing wild-world input (imported decks, model output) can degrade per element instead of failing the document; normalizeSlide itself stays unary (slides.map(normalizeSlide) keeps working).
version.ts Serialized-contract version + migration registry: DSL_VERSION, the DSL_MIGRATIONS ladder, and the pure migrate / dslVersionOf / needsMigration runner.
import type { Slide, PPTElement, Action } from '@openmaic/dsl';
import { isTextElement, DSL_VERSION, SYNC_ACTIONS } from '@openmaic/dsl';

Runtime layer (schema + validators + normalizers)

The contract is enforceable two ways — a zero-dependency in-process validator and a cross-language JSON Schema — both generated from / aligned to the same public TS types, and both honoring the zero-runtime-dependency invariant; a third zero-dependency normalize* family repairs a document to satisfy them:

  1. JSON Schema artifacts (cross-language mirror) — Stage, the default Scene<Action, SceneContent>, and Action are emitted as standalone JSON Schema at build time and shipped. This is the language-neutral mirror of the contract for non-TS consumers, and the place to go for exhaustive value-level (type / format) checking:

    import stageSchema from '@openmaic/dsl/schema/stage.schema.json' with { type: 'json' };
    import sceneSchema from '@openmaic/dsl/schema/scene.schema.json' with { type: 'json' };
    import actionSchema from '@openmaic/dsl/schema/action.schema.json' with { type: 'json' };
    // feed to any JSON Schema validator (ajv, or a non-TS / non-JS consumer)
    

    The schema is generated from the TS types (the single source of truth) by ts-json-schema-generator, a devDependency — it never enters the runtime dependency set.

  2. Pure validators (in-process boundary) — validate* are hand-written, zero-dependency checks layered on the guards: object shape, required fields (including each action variant's, e.g. a spotlight's elementId), known discriminants, and the scene type <-> content binding the public Scene type enforces. Because they add no dependency, in-process (TS / JS) producers and consumers — generators, importers, the runtime engine — can rely on them directly without shipping a schema validator. They are a structural subset of the schema (presence + discriminants; the schema additionally checks each field's value shape), and describe the same contract. Both are kept in lockstep by a test that pins the validators' per-variant required fields to the generated schema.

    import { validateStage, validateScene, validateAction } from '@openmaic/dsl';
    
    const result = validateScene(input);
    if (!result.valid) throw new Error(result.errors.map((e) => `${e.path}: ${e.message}`).join('; '));
    

    ValidationResult is { valid: true } | { valid: false; errors: { path; message }[] } — it collects every issue rather than failing on the first.

  3. Pure normalizers (repair boundary) — where validate* reports on a document, normalize* repairs one, so producers stop carrying their own imperative "fix up the output" pass. normalizeElement (and the normalizeSlide / normalizeScene / normalizeStage walkers) fill the required fields a producer may have left off, derive geometry-dependent fields (a line's start / end, a shape's viewBox / path), and fail loud on a present-but-wrong-typed field — returning a fully-defaulted document that then satisfies the validators. Pure and non-mutating; idempotent.

    The static defaults (ELEMENT_DEFAULTS) are the single source of truth and also ride out on the JSON Schema as @default annotations (so non-TS consumers ship them too); a test pins the two together. normalize* owns only the producer-independent defaults — media-specific reconciliation (e.g. fitting an image box to a resolved asset's real dimensions) stays a producer concern.

    Scope: normalize* owns element content (the per-variant required fields

    • derivable geometry). It does not fill or check the base identity / geometry every element shares (id, left / top / width / height / rotate) — those are producer-supplied (the id is often assigned downstream) and carry no content default. normalize* and validate* are complementary: normalize repairs content, validate / the schema check the full structure.
    import { normalizeElement, normalizeScene, ELEMENT_DEFAULTS } from '@openmaic/dsl';
    
    const el = normalizeElement(rawElement); // required fields filled, geometry derived
    const scene = normalizeScene(rawScene); //  walks the slide canvas + whiteboards
    

Version & migration

Two version numbers live in this package and do not track each other:

  • the npm package version (package.json) — the semver of the code/API artifact; bumps when exports or behavior change.
  • DSL_VERSION — the version of the serialized slide contract (the on-disk document shape). It bumps only when a persisted document's shape changes, independent of package releases. (A third, finer axis — SlideContent.schemaVersion — versions the PPTist canvas inside a slide and is migrated app-side; it is orthogonal to DSL_VERSION.)

version.ts owns the document-level migration mechanism, zero-dependency and pure like the validators:

import { DSL_VERSION, migrate, dslVersionOf, needsMigration } from '@openmaic/dsl';

const current = migrate(doc); // walks doc from its written version up to DSL_VERSION
  • DSL_MIGRATIONS is an ordered ladder of { from, to, migrate } steps; each step's to is the next step's from, and the last reaches DSL_VERSION.
  • migrate(doc) reads the document's version from its dslVersion envelope field (absent ⇒ treated as legacy/unversioned), walks the ladder applying each pure transform, and stamps the result. It is idempotent (a current document is returned as-is), forward-compatible (a document stamped newer than DSL_VERSION is returned untouched, never silently downgraded), and fail-loud (a gap in the ladder throws rather than yielding a half-migrated document).

The first ladder entry is a no-op transform that stamps legacy documents up to the current DSL_VERSION: promoting Action into the contract and adding validators did not change any serialized shape, so the current on-disk shape already is 0.1.0. The entry wires the pipeline end to end and gives real documents a version to migrate forward from; the first real transform is appended (and DSL_VERSION bumped) when the serialized shape first changes.

Which aggregate carries the dslVersion field — a whole Stage, a single Scene row, or a bundle — is left to the store that first consumes this pipeline; the runner only needs the envelope field.

Runtime envelope (#869)

Learner-produced runtime data (chat, quiz attempts, playback facts) is persisted outside the document, per learner, through a RuntimeStore (@openmaic/storage). This package owns the envelope: RuntimeSession (identity + lifecycle, keyed by stage/learner/kind) and RuntimeRecord<TPayload> (ordered facts; the store-assigned seq is the replay ordering key). Core-kind payload skeletons (chat, quizAttempt) live here; payload internals are app-owned, validated at the store boundary via injected validators (runtime.ts guards + validate.ts). A RuntimeSession carries its own version envelope field, runtimeDslVersion — mechanically disjoint from a document's dslVersion — and rides its own version line: RUNTIME_DSL_VERSION and a dedicated RUNTIME_DSL_MIGRATIONS ladder, walked by migrateRuntime (not migrate), with runtimeDslVersionOf / needsRuntimeMigration as the runtime-line counterparts of dslVersionOf / needsMigration.

Unlike the document line, the runtime line has no unversioned epoch. Real pre-versioning documents exist, so migrate lifts an unstamped document from UNVERSIONED_DSL_VERSION via its first ladder entry. Nothing legitimately predates the runtime envelope, though — it is a brand-new contract, and the future RuntimeStore stamps RUNTIME_DSL_VERSION at write time. So a RuntimeSession is born stamped (runtimeDslVersion is a required field, not optional), RUNTIME_DSL_MIGRATIONS ships empty (no legacy-lift entry; the first real runtime shape change appends a step from the pinned INITIAL_RUNTIME_DSL_VERSION and bumps RUNTIME_DSL_VERSION), and an unstamped object reaching any runtime-line function (migrateRuntime, needsRuntimeMigration, runtimeDslVersionOf) throws — it is a misrouted legacy document or an unstamped producer write, not legacy data to lift. (Non-objects stay exempt: they are not migratable aggregates and read as unversioned on every line.) An empty ladder is still fully functional — a stamped-current session early-returns as already current, and a session stamped at an unknown older version hits the "no migration path" fail-loud.

The two lines stamp different fields, so neither ladder reads the other's version — but disjoint fields alone are not enough: a session lacking dslVersion would still read as unversioned to the document runner and be lifted onto the wrong line. The cross-line guard — enforced in the shared envelope reader, so the plain dslVersionOf / runtimeDslVersionOf reads, the needs*Migration predicates, and the runners all give one answer per envelope — closes this with three-case semantics: (1) own line's stamp present → migrate normally on the own line, regardless of the other key; (2) both stamps absent → genuine legacy data, walk the own ladder; (3) own stamp absent but the sibling line's stamp present → throw. Case (3) is undecidable from the envelope — the other line's aggregate misrouted here is byte-identical to this line's data carrying a stray foreign stamp; migrating would mangle the former, returning it unchanged would permanently orphan the latter from its own line — so it is treated like a malformed stamp and fails loud. validateRuntimeSession likewise rejects a session missing its runtimeDslVersion (born stamped, no legacy epoch) and a stray dslVersion on a session at the door. The runner mechanism (contiguous ladder, idempotent, forward-compatible, fail-loud) is shared; only the ladder, target version, own stamp field, and the sibling field the guard checks differ.

Status

Both consumers are now wired to @openmaic/dsl and no longer vendor their own copy of the slide types:

  • @openmaic/importer: imports all slide types from @openmaic/dsl; vendored openmaic/types/slides.ts deleted. The importer emits complete DSL Slide objects directly (the old partial "draft slide" + post-fill step is gone).
  • @openmaic/renderer: imports all slide types from @openmaic/dsl; vendored types/slides.ts deleted. @openmaic/dsl is a regular dependency, kept external in the rollup build so consumers share one copy. The public @openmaic/renderer/types surface now re-exports the DSL types.

Roadmap

  • Wire @openmaic/importer to import types from @openmaic/dsl (vendored copy deleted).
  • Wire @openmaic/renderer to import types from @openmaic/dsl (vendored copy deleted).
  • Add the JSON Schema for the slide contract + a pure schema validator (build-time dist/schema/*.json via a devDep generator; zero-dep validate* functions). See Runtime layer below.
  • Promote the stage / scene / scene-content types into the DSL (the universal skeleton now lives in stage.ts).
  • Bring the Action playback verb set into the DSL (action.ts); the widget interaction actions graduated into the contract once they decoupled from widget configs, so the standard Action union now covers them too. Scene<TAction> defaults to that union; PBL configs and the app's richer content kinds still plug in via Scene's generics.
  • Activate the migration registry: version.ts ships the DSL_MIGRATIONS ladder and a pure migrate runner (idempotent, forward-compatible, fail-loud), no longer a stub. See Version & migration above.
  • Own element defaulting in the contract: normalize.ts ships the pure normalize* family + ELEMENT_DEFAULTS, and the static defaults ride out on the JSON Schema as @default annotations. Producers drop their imperative "fix up the output" passes. See Runtime layer above.
  • Reserve @openmaic/exporter as the 4th family member.

Stage / Scene split

stage.ts owns the universal lesson skeleton: Stage, the discriminated SceneContent (SlideContent | QuizContent), and a generic

interface Scene<TAction = Action, TContent extends { type: SceneType } = SlideContent | QuizContent>

TAction defaults to the contract's standard Action union (defined in action.ts), so a scene carries playback actions out of the box; skeleton-only consumers that reject actions opt out with Scene<never, …>. Apps widen the content union (and, if they add their own actions, the action union) by injecting their own types:

import type { Scene, Action } from '@openmaic/dsl';
type AppScene = Scene<Action, SlideContent | QuizContent | InteractiveContent | PBLContent>;

Widget configs (WidgetType / WidgetConfig) and PBLProjectConfig remain out of scope here — they're faster-moving product surfaces that stay app-side and plug in via Scene's generics. The widget actions (widget_highlight, widget_setState, …), by contrast, are config-free playback verbs and live in action.ts with the rest of the Action union.

Divergence reconciled (seed provenance)

The seed is the app's lib/types/slides.ts, but before this package existed the contract had been copy-pasted into three places that drifted apart. This package is the canonical superset: every field that existed in any copy is kept, so consumers can adopt the DSL without losing data. Merged-in fields are annotated @since-merge in slides.ts.

Field app lib/types renderer copy importer copy DSL decision
PPTTextElement.vAlign — ✓ ✓ kept
PPTImageElement.softEdge — ✓ ✓ kept
TableCellBorder + TableCell.borders — ✓ ✓ kept
TableCell.padding — ✓ ✓ kept
TableCell.vAlign — top/middle/bottom up/mid/down/top/middle/bottom canonical = top/middle/bottom; importer already normalizes its up/mid/down aliases in transformParsedToSlides
PPTTableElement.rowHeights — ✓ ✓ kept
Slide.script (speaker notes) — — ✓ kept
Slide.viewportSize/viewportRatio/theme required required optional canonical = required; importer now fills them at construction in transformParsedToSlides (no partial/draft stage)
SlideData (deprecated) ✓ — ✓ kept, @deprecated

The importer conforms to the canonical contract: it normalizes cell vAlign aliases and emits the required Slide fields on output. The renderer consumes the same superset (it gains access to script and the importer-origin fields it didn't previously declare).

Build

Pure TypeScript compiled with tsc to ESM + .d.ts, then the JSON Schema artifacts are generated into dist/schema/:

pnpm --filter @openmaic/dsl build         # -> dist/ (index.js, index.d.ts, …) + dist/schema/*.json
pnpm --filter @openmaic/dsl build:schema  # regenerate only dist/schema/*.json
pnpm --filter @openmaic/dsl typecheck
pnpm --filter @openmaic/dsl test

License

MIT, matching the rest of the family (@openmaic/dsl, @openmaic/importer, @openmaic/renderer) and the OpenMAIC root, so the license policy is uniform across the SDK.