Skip to main content

Artifact Interface Contract (AIC)

Status: Draft v0.1.1 Host System: Aptlantis Studio Compatible With: SESM v0.3.x, NIPC v0.1.x, Neon Ink v0.1.x, APGC v0.1.x Scope: Contract layer that defines how structured data, SESM metadata, NIPC palette semantics, and Neon Ink brand expression become deterministic rendered artifacts in SVG, HTML, and related brand surfaces.

Source: Docs/AIC-v0.1.1.md (this is the only version of AIC in the source tree — no legacy duplicate exists).

1. Overview​

The Artifact Interface Contract (AIC) is the bridge between SESM, NIPC, and Neon Ink.

Technical Integration
├── SESM        → Embedded JSON, Semantic Capsule, Provenance
├── NIPC        → Color Families, Psychological Intent, Hue vs Intensity
└── AIC         → Deterministic Output, Required Fields, Layout Regions

SESM defines what an artifact means structurally. NIPC defines what color semantics, families, psychological intent, and intensity mean. Neon Ink defines how the brand behaves visually and verbally. AIC defines how the system turns those meanings into consistent rendered artifacts.

DATA -> SESM -> AIC -> SVG/HTML -> USER

In this flow:

  • Data provides source records, manifests, pipeline output, and content.
  • SESM describes identity, semantics, provenance, links, crawl hints, LLM hints, and UI hints.
  • NIPC supplies semantic role, semantic family, psychological intent, palette validation, and intensity rules.
  • AIC defines artifact types, required fields, layout regions, render targets, state behavior, and interaction rules.
  • Neon Ink supplies typography, density, panel grammar, page composition, and brand voice.
  • SVG/HTML delivers the final interface.

AIC exists to prevent design drift. Given the same source data, SESM block, artifact type, and Neon Ink version, the generator should produce the same artifact structure every time.

AIC Mindmap

2. Relationship To SESM, NIPC, And Neon Ink​

2.1 Layer Responsibilities​

LayerCanonical DocumentResponsibility
MeaningSESM standardEmbedded metadata, artifact identity, provenance, links, agent/crawler hints
PaletteNIPCPalette families, semantic roles, psychological intent, intensity, palette validation
ContractThis document (AIC)Artifact type contract, required fields, layout regions, render targets, state mapping
ExpressionNeon InkBrand expression, typography, panel grammar, page composition, brand voice

2.2 What SESM Answers​

  • What is this artifact? Where did it come from? What data or template produced it? What does it mean? Where should agents, crawlers, or users go for canonical context?
{
  "sesm_version": "0.3.0",
  "asset": {
    "id": "rust-code-corpus-card",
    "role": "dataset-card",
    "title": "Rust Code Corpus"
  },
  "theme": {
    "id": "neon-ink",
    "semantic_role": "code-heat",
    "semantic_family": "creation-build-code",
    "psychological_intent": "signal-hands-on-code-build-work",
    "intensity": 2,
    "state": "active"
  }
}

2.3 What NIPC Answers​

  • Which semantic role should carry the hue? Which family groups that role? What psychological purpose does the color serve? What intensity is appropriate before the UI becomes noisy? Which palette usages should validators warn about?
{
  "semantic_role": "pipeline",
  "semantic_family": "process-transformation",
  "psychological_intent": "explain-system-flow",
  "intensity": 2,
  "priority": "medium"
}

2.4 What Neon Ink Answers​

  • How should panels, typography, density, and page composition behave? What does an Aptlantis Studio surface feel like? Which brand voice rules apply?

2.5 What AIC Answers​

  • What must a dataset-card display? Which fields are required, optional, derived, or hidden? Which spatial regions does the artifact use? Which fields render into SVG, HTML, metadata, or all three? How does state map to border, glow, animation, and interaction? What validates whether an artifact is contract-compliant?
{
  "aic_version": "0.1.0",
  "artifact_type": "dataset-card",
  "required_fields": ["title", "dataset_id", "state", "records", "tokens"],
  "layout": {
    "regions": ["icon", "title", "tags", "description", "stats", "actions", "state_badge"]
  }
}

3. Goals​

AIC is designed to:

  1. Make rendered artifacts deterministic.
  2. Bind SESM metadata to Neon Ink visual semantics.
  3. Define canonical artifact types for the Aptlantis Studio website and generator.
  4. Separate SVG responsibilities from HTML responsibilities.
  5. Prevent field, layout, and state drift across pages.
  6. Make artifact generation testable.
  7. Support validators, preview engines, editors, diff tools, and future visual builders.
  8. Preserve local-first archival meaning.
  9. Keep dense interfaces scannable and semantically consistent.
  10. Allow theme variants without breaking core artifact contracts.

4. Non-Goals​

AIC does not replace SESM metadata, replace Neon Ink visual rules, define all dataset schemas, define all Rust generator internals, require every artifact to be SVG, require JavaScript for basic meaning, define access control/authentication/private metadata policy, force marketing graphics to expose full technical metadata, or define a complete design tool file format.

AIC is a rendering contract, not a storage format or brand manual.

5. Terminology​

  • Artifact Type: A stable named primitive the generator can render, such as dataset-card, pipeline-panel, or qa-item.
  • Contract: The required fields, optional fields, layout regions, render targets, state behavior, and validation rules for an artifact type.
  • Region: A named spatial slot in an artifact layout (icon, title, tags, stats, actions, state_badge).
  • Render Target: The output context where a field or region appears (svg, html, sesm, brand).
  • Visible Field: A field that must be shown to the user in the rendered UI.
  • Embedded Field: A field that must be preserved in SESM or machine-readable metadata, whether or not it appears visually.
  • Derived Field: A field computed from source data, such as quality_label from quality_score.
  • Canonical Action: The primary destination or operation for an artifact.

6. AIC Block Structure​

{
  "aic_version": "0.1.0",
  "artifact_type": "dataset-card",
  "compatible_with": {
    "sesm": "0.3.x",
    "nipc": "0.1.x",
    "neon_ink": "0.1.x",
    "apgc": "0.1.x"
  },
  "fields": {},
  "theme": {},
  "layout": {},
  "semantic_mapping": {},
  "state_mapping": {},
  "fallback_rules": {},
  "render": {},
  "render_targets": {},
  "interaction": {},
  "validation": {}
}

The contract may live as a standalone JSON or TOML contract file, embedded generator configuration, documented Markdown examples, a Rust struct/enum representation, or a validation schema. It should remain stable enough that old artifacts can be validated years later.

7. Canonical Artifact Types​

{
  "artifact_types": [
    "dataset-card",
    "dataset-header",
    "pipeline-panel",
    "qa-item",
    "stats-tile",
    "theme-board"
  ]
}

Artifact type names must be lowercase and hyphen-separated. Other useful shapes (navigation-card, related-dataset-list, download-card, schema-card, quality-report-panel, compatibility-panel, brand-promo-panel) are extension contracts until promoted into a later AIC version.

Artifact TypeDefinition
dataset-cardCompact dataset preview artifact.
dataset-headerPrimary dataset identity artifact.
pipeline-panelPipeline state and execution artifact.
qa-itemIndexed documentation or FAQ artifact.
stats-tileSingle metric artifact.
theme-boardPalette and theme identity artifact.

8. Global Field Contract​

All generated artifacts should support a shared identity core.

8.0 Required Fields​

Required fields are never guessed:

{
  "qa-item": {
    "required": ["question", "category", "id"],
    "optional": ["answer", "tags", "state"]
  }
}

If a required field is missing, production generation fails. Preview generation may emit a warning artifact, but must not silently invent missing data.

8.1 Required Embedded Fields​

{
  "artifact_id": "rust-code-corpus-card",
  "artifact_type": "dataset-card",
  "state": "active",
  "semantic_role": "code-heat",
  "semantic_family": "creation-build-code",
  "psychological_intent": "signal-hands-on-code-build-work",
  "intensity": 2,
  "source_manifest": "data/datasets/rust-code-corpus.json",
  "template_id": "dataset-card-v1"
}

Every non-decorative artifact should visibly expose: title or label; artifact type, category, or role; state when it matters; primary semantic accent; at least one trust or navigation cue.

Visible fields render into SVG, HTML, or both. Embedded fields are stored in SESM or other machine-readable payloads even when not shown in the UI.

8.3 Required Compatibility Fields​

{
  "aic_version": "0.1.0",
  "sesm_version": "0.3.0",
  "theme_id": "neon-ink",
  "theme_version": "0.1.0"
}

8.4 Theme Styling Object​

{
  "theme": {
    "id": "neon-ink",
    "palette_contract": "nipc-0.1",
    "semantic_role": "pipeline",
    "semantic_family": "process-transformation",
    "psychological_intent": "explain-system-flow",
    "state": "active",
    "intensity": 2,
    "glow": "soft",
    "priority": "medium"
  }
}

9. Artifact Contracts​

9.1 dataset-card​

Use for compact dataset previews on home, category, related, and listing pages.

{
  "artifact_type": "dataset-card",
  "required": ["title", "dataset_id", "state", "semantic_role", "semantic_family", "records", "tokens"],
  "optional": ["description", "icon", "tags", "license", "quality_score", "size", "created", "updated", "models_supported", "canonical_html"],
  "layout": {
    "regions": ["icon", "title", "tags", "stats", "actions", "status"],
    "flow": "left-icon-right-content",
    "density": "compact"
  },
  "render": {
    "svg": ["icon", "title", "tags", "core_stats", "state_badge"],
    "html": ["actions", "tooltips", "expanded_metadata"],
    "sesm": ["all_identity_fields", "provenance", "links", "theme"]
  }
}

Minimum visible stats: records, tokens. Recommended: records, tokens, size, license.

9.2 dataset-header​

Use for primary dataset identity panels.

Required: title, dataset ID, state, semantic role, description, tags, records, tokens, license, updated date, canonical action. Recommended: quality score, created date, size, latest pipeline run, version, supported formats.

{
  "regions": ["breadcrumb", "icon", "title", "tags", "description", "primary_stats", "actions", "state_summary", "quality_summary"],
  "flow": "identity-left-state-right",
  "density": "detailed"
}

9.3 pipeline-panel​

Use for a pipeline run summary.

Required: pipeline ID, state, associated dataset, stage list, updated/completed timestamp. Recommended: records changed, tokens changed, warnings, errors, report link, build ID.

Render behavior: running uses violet border and pulse; complete/verified uses green status marks; warning uses yellow caveat markers; error uses red failure markers.

9.4 stats-tile​

Required: label, value, semantic role. Optional: unit, trend, timestamp, source, tooltip.

Rules: do not glow unless the stat represents live state; use mono labels; keep values readable at a glance.

9.5 qa-item​

Required: question, category, id. Optional: answer, tags, state, related links, source document, last updated, confidence, expanded state.

{
  "regions": ["index", "semantic_indicator", "title", "toggle", "body", "links"],
  "flow": "indexed-accordion",
  "density": "compact"
}

The semantic indicator is required for scannability.

9.6 theme-board​

Required: theme ID, theme name, version, background layer swatches, semantic role swatches, state behavior examples. Recommended: typography samples, component examples, SESM theme block, token export, intended surfaces.

10. Semantic To Visual Mapping​

AIC maps source state and NIPC semantic role to visual behavior. NIPC provides hue, family, psychological intent, and intensity rules. Neon Ink provides the surrounding visual grammar.

10.0 Semantic Mapping​

{
  "semantic_mapping": {
    "code_heat": { "color": "orange", "border": true, "accent_weight": "primary" },
    "process": { "color": "violet", "glow": "pulse" }
  }
}

Semantic mapping must not override the artifact's state. For example, a pipeline-panel may use process as its primary semantic role while a small state marker uses success, caution, or critical.

10.1 State Mapping​

{
  "state_mapping": {
    "idle": { "border": "archive", "glow": "none", "animation": "none", "intensity": 0 },
    "active": { "border": "info", "glow": "soft", "animation": "none", "intensity": 2 },
    "running": { "border": "process", "glow": "pulse", "animation": "pulse", "intensity": 4 },
    "featured": { "border": "featured", "glow": "soft", "animation": "none", "intensity": 3 },
    "complete": { "border": "success", "glow": "soft", "animation": "none", "intensity": 2 },
    "verified": { "border": "success", "glow": "soft", "animation": "none", "intensity": 2 },
    "warning": { "border": "caution", "glow": "soft", "animation": "none", "intensity": 3 },
    "error": { "border": "error", "glow": "sharp", "animation": "none", "intensity": 4 },
    "archived": { "border": "archive", "glow": "none", "animation": "none", "intensity": 0 },
    "experimental": { "border": "experimental", "glow": "soft", "animation": "none", "intensity": 2 }
  }
}

10.2 Color Intensity Rules​

color hue = semantic role
brightness/glow/animation = state strength or activity

Examples: faint cyan = idle structure; soft cyan = active structure; pulsing violet = running process; strong red = critical failure; muted slate = archived artifact.

IntensityNameUse
0mutedarchived, unknown, background metadata
1whispertiny dot, thin rail, subtle label
2softnormal tags, semantic indicator
3activeselected item, highlighted card
4urgentwarning, running, featured
5interrupterror or critical blocker only

10.3 Confidence Layers​

{
  "confidence": {
    "trust_level": "high",
    "completeness": 0.92,
    "reproducibility": 0.98,
    "validation": "verified"
  }
}
Confidence SignalVisual Expression
High truststable green or cyan indicator
Incompleteyellow indicator or partial bar
Low reproducibilitywarning badge
Failed validationred badge and report link
Unknownmuted metadata state

Confidence should never replace explicit validation text. It should add scan-level meaning.

10.4 NIPC Palette Validation​

AIC validators should warn when: red/risk roles are used for non-risk decoration; green/trust roles appear without evidence fields; yellow/attention roles dominate a surface instead of acting as markers; a compact artifact uses more than one dominant semantic family; a qa-item lacks a semantic indicator; a pipeline uses status color as the main hue instead of process/pipeline plus a small state marker.

11. SVG vs HTML Responsibility​

11.1 SVG Responsibilities​

Artifact identity, title, primary semantic role, state indicator, compact visible metadata, core stats, tags when compact enough, embedded SESM metadata, stable visual layout. Best for: dataset cards, dataset headers, pipeline panels, static timeline snapshots, theme boards, navigation cards, related dataset panels, promotional artifact panels.

11.2 HTML Responsibilities​

Page layout, interactive controls, search/filter/sort, expanded metadata, keyboard focus behavior, tooltips, long-form text, responsive reflow, analytics hooks, download controls, forms/user input.

HTML can wrap SVG artifacts, expose the same canonical data, and add interactions without changing the underlying artifact meaning.

11.3 Shared Responsibilities​

Title, state, tags, primary stats, canonical action may show in both SVG and HTML — but they must derive from the same source manifest or compiled artifact payload.

11.4 Render Target Contract​

{
  "dataset-card": {
    "render": { "svg": ["core_stats", "title", "tags"], "html": ["interactive_controls", "expanded_sections"] },
    "render_targets": {
      "svg": ["title", "tags", "icon", "state_badge", "records", "tokens"],
      "html": ["canonical_link", "hover_metadata", "tooltip", "expanded_stats", "interactive_controls"],
      "sesm": ["artifact_id", "asset.role", "theme", "provenance", "links", "crawl", "llm"]
    }
  }
}

12. Interaction Contracts​

Interactions should be declared through AIC and reflected in SESM ui.interaction where useful.

{
  "interaction": {
    "click": "canonical_html",
    "hover": "show-metadata",
    "focus": "highlight-border",
    "keyboard": "activate-canonical-action"
  }
}

Common click targets: canonical_html, download, pipeline_report, manifest, schema, related_dataset, none.

Hover metadata may show artifact ID, source manifest, state, last updated, quality score, provenance summary — but must not be the only place critical warnings appear.

Keyboard focus should use semantic border highlight, preserve visible focus, not rely only on glow, and expose accessible label text in HTML.

13. Generator Contract​

source manifest
  -> normalize fields
  -> resolve artifact type
  -> validate required fields
  -> resolve SESM block
  -> resolve Neon Ink tokens
  -> apply AIC layout contract
  -> render SVG/HTML
  -> validate output

Given identical inputs, generator version, template ID, AIC version, SESM version, and Neon Ink version, output should be structurally identical except for explicitly volatile fields such as timestamps or build IDs.

Templates should be named and versioned (dataset-card-v1, pipeline-panel-v1, qa-item-v1, theme-board-v1) and appear in SESM artifact.template_id.

13.4 Missing Field Behavior​

If a required field is missing, production builds should fail validation; preview builds may render a warning artifact; missing fields must not silently become blank in final output. If an optional field is missing, the region may collapse, layout must remain stable, and SESM should omit unknown values rather than invent them.

13.5 Fallback Rules​

Recommended fallback priority: source manifest field → derived field → SESM metadata field → theme default → explicit unknown/muted state. Never guess license, validation, provenance, or quality fields.

{
  "fallback_rules": {
    "missing_license": "omit",
    "missing_validation": "omit",
    "missing_stats": "hide_region"
  }
}
ActionMeaning
failStop production generation because a required field is missing
omitLeave unknown optional data out of visible UI and embedded metadata
hide_regionCollapse the affected optional layout region
muted_unknownRender an explicit unknown state for non-critical data
preview_warningRender a warning artifact in preview builds only

14. Validation Rules​

14.1 Global Validation​

Artifact type is canonical or explicitly namespaced; required fields exist; required visible fields render; required embedded fields exist in SESM; theme.id is present; state uses a recommended state name or namespaced extension; semantic_role/semantic_family use NIPC names or namespaced extensions; psychological_intent is present for generated semantic artifacts; intensity is within the NIPC 0–5 scale; canonical links are valid when declared; output dimensions and layout regions are valid.

14.2 Artifact-Specific Validation​

  • dataset-card: title visible; dataset ID embedded; records and tokens visible; state embedded; semantic role embedded; canonical action available when used as navigation.
  • pipeline-panel: pipeline ID visible or embedded; state visible; stages exist; associated dataset exists; status color matches state mapping.
  • qa-item: index visible; title visible; semantic indicator visible; body available in HTML or expanded target.
  • theme-board: background swatches visible; core semantic swatches visible; theme ID and version embedded or shown.

14.3 Visual Validation​

No clipped text; no overlapping critical labels; readable contrast; stable layout after optional fields collapse; correct semantic color usage; correct glow/state behavior; visible focus in HTML wrappers.

14.4 Metadata Validation​

Valid JSON; valid sesm_version; valid asset.role; valid theme.id; valid provenance for generated artifacts; no secrets or private paths; no unsupported required fields.

14.5 Geometry Validation (APGC)​

When APGC geometry is specified, additionally validate: shape_family is a recognized APGC family name; angle_energy is within 0–5 and within the range permitted by the chosen shape family; declared safe zone is honored; corner profile is recognized; for error/critical artifacts, angle_energy does not exceed 2; if a responsive fallback shape is declared, it is a valid APGC shape family.

Geometry validation is advisory in v0.1. Violations should produce warnings, not hard failures.

15. Compatibility & Versioning​

{
  "aic_version": "0.1.1",
  "sesm_version": "0.3.0",
  "nipc_version": "0.1.0",
  "neon_ink_version": "0.1.0",
  "apgc_version": "0.1.0"
}
AIC VersionSESM VersionNIPC VersionNeon Ink VersionAPGC VersionStatus
0.1.x0.3.x0.1.x0.1.x0.1.xSupported

Custom artifact types should be namespaced (aptlantis.dataset-map, aptlantis.model-card, experimental.world-panel). Core AIC artifact types stay lowercase and hyphen-separated.

Breaking changes include: removing required fields, renaming canonical artifact types, changing required layout regions, changing state meanings, changing render target responsibilities. Breaking changes increment the major version; additive artifact types, optional fields, and new validation recommendations may increment the minor version.

16. Example Complete Contract​

{
  "aic_version": "0.1.0",
  "artifact_type": "dataset-card",
  "compatible_with": { "sesm": "0.3.x", "nipc": "0.1.x", "neon_ink": "0.1.x", "apgc": "0.1.x" },
  "fields": {
    "required": ["title", "dataset_id", "state", "semantic_role", "semantic_family", "psychological_intent", "intensity", "records", "tokens"],
    "optional": ["description", "icon", "tags", "license", "quality_score", "size", "updated", "canonical_html"],
    "embedded": ["artifact_id", "source_manifest", "template_id", "provenance", "theme"],
    "visible": ["title", "tags", "records", "tokens", "state_badge"]
  },
  "layout": { "regions": ["icon", "title", "tags", "stats", "actions", "status"], "flow": "left-icon-right-content", "density": "compact" },
  "semantic_mapping": {
    "code_heat": { "color": "orange", "border": true, "accent_weight": "primary" },
    "process": { "color": "violet", "glow": "pulse" }
  },
  "state_mapping": {
    "archived": { "intensity": 0 },
    "active": { "border": "info", "glow": "soft", "animation": "none", "intensity": 2 },
    "running": { "border": "process", "glow": "pulse", "animation": "pulse", "intensity": 3 },
    "success": { "intensity": 3, "color_override": "green" }
  },
  "theme": {
    "id": "neon-ink",
    "palette_contract": "nipc-0.1",
    "semantic_role": "code-heat",
    "semantic_family": "creation-build-code",
    "psychological_intent": "signal-hands-on-code-build-work",
    "state": "active",
    "intensity": 2,
    "glow": "soft",
    "priority": "medium"
  },
  "fallback_rules": { "missing_license": "omit", "missing_validation": "omit", "missing_stats": "hide_region" },
  "render": { "svg": ["core_stats", "title", "tags"], "html": ["interactive_controls", "expanded_sections"] },
  "render_targets": {
    "svg": ["icon", "title", "tags", "records", "tokens", "state_badge"],
    "html": ["canonical_link", "hover_metadata", "expanded_stats"],
    "sesm": ["asset", "artifact", "theme", "ui", "crawl", "llm", "links", "provenance"]
  },
  "interaction": { "click": "canonical_html", "hover": "show-metadata", "focus": "highlight-border" },
  "validation": { "fail_on_missing_required": true, "allow_missing_optional": true, "require_sesm": true, "require_theme": "neon-ink" }
}

17. Implementation Notes For Rust Generators​

enum ArtifactType {
    DatasetCard,
    DatasetHeader,
    PipelinePanel,
    QaItem,
    StatsTile,
    ThemeBoard,
}

Recommended generator modules:

contracts/
  artifact_type.rs
  fields.rs
  layout.rs
  state_mapping.rs
  validation.rs

render/
  svg/
  html/
  sesm/

themes/
  neon_ink.rs

Recommended validation sequence:

parse source -> normalize -> validate AIC -> validate SESM -> render -> inspect output

18. Summary​

AIC is the binding contract that makes Aptlantis Studio's visual system deterministic.

SESM says what an artifact is.
Neon Ink says what meaning looks like.
AIC says exactly how it renders.
Dataset JSON -> SESM Enrichment -> AIC Validation -> SVG Template -> Compiled Artifact

Into this:

dataset.json -> SESM -> AIC -> Neon Ink SVG/HTML artifact

The result is a system where design is schema-aware, UI is a compiled artifact, color carries meaning, SVG becomes a transport layer, pages can be regenerated consistently, and validators/preview tools can enforce the contract.

AIC is the layer that keeps Aptlantis Studio from becoming merely themed. It keeps the interface derived.