Design model

Platform spec article

Design model

Back to Project manifest contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-hub-authority Hub authority Accepted

   Hub authority

   Context

   Consumers need one contract.

   Decision

   Hub owns Project.proj normative text.

   Consequences

   Mod/Template on hub.

   Verification anchors

   manifest tests.

   Open full ADR page

2. 0002-mod-and-template-project-types Mod and Template types Accepted

   Mod and Template types

   Context

   Discriminate project kinds.

   Decision

   May declare type Mod or Template; hosts use Host + corelib.

   Consequences

   Links to mods/scaffolding.

   Verification anchors

   project fixtures.

   Open full ADR page

Articles

• Contracts and edge cases Strict guarantees and failure modes for Mod project manifests. article Standard Reviewed Wed May 20
• Design model Conceptual model for `Project manifest contract` and its subsystem boundaries. article Standard
• Examples Concrete examples for `Project manifest contract` decisions and usage patterns. article Standard Reviewed Wed May 20
• FAQ and troubleshooting Project manifest tooling FAQ. article Standard
• Flow and algorithm Manifest validation and Mod package discovery flow. article Standard Reviewed Wed May 20
• Project link libraries Normative project.link block for Extern library resolution at link time (v0.3). article Standard Reviewed Wed May 20
• Verification and traceability Verification for tooling-side project manifest contracts. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 5 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Manifests and lockfiles

  Parent area

• Feature
  Project manifest contract

  Parent feature hub

• Feature
  Workspace and lock contracts

  Reserved workspace keys and lockfile interaction

• Feature
  Project manifest contract (compiler)

  defers-to — manifest-band diagnostics and graph validation

Purpose

Tooling-facing shape of Project.proj: project kind, mod orchestration block, template metadata, readme publishing, and host app launch rules. Resolution-graph behavior and diagnostic bands live in Project manifest contract (compiler)—this article does not duplicate full manifest key tables from the manifests area hub.

Project kinds

flowchart LR
  Host[Host default]
  Mod[Mod]
  Tpl[Template]
  Host -->|implicit corelib| Tooling[CLI / LSP / pack]
  Mod -->|AOT + SDK| Tooling
  Tpl -->|packageKind template| Pack[beskid pckg pack]

project.type	Role
(omitted)	Host — default application or library project
Mod	Compiler-mod package (see below)
Template	Template authoring; published as packageKind: template

Unknown project.type values must be rejected at structural parse time.

Implicit corelib (host projects)

Every host project must resolve corelib through toolchain defaults. Manifests must not define noCorelib, useCorelib: false, or equivalent opt-out keys.

Package readme (readme)

The project block may include readme = "relative/path.md". When omitted, tooling treats readme.md at the project root as the default when present. beskid pckg pack publishes the resolved file as root README.md in the .bpk artifact.

Mod project type (Mod)

When set to Mod, the manifest denotes a compiler-mod package discovered through dependency resolution, compiled AOT, and loaded via SDK contracts during host compilation. User-visible contract semantics: Compiler Mod SDK.

On-disk nesting

project:
  name: ...
  type: Mod
  mod:
    maxGeneratorRounds: 4
    capabilities: [emit_syntax]

Normative project.mod keys (v0.2 target)

Key	Required	Meaning
maxGeneratorRounds	no	Positive cap on generator replay; default 4
capabilities	no	Closed vocabulary (emit_syntax, read_project_sources, query_semantic_snapshot, extern_ffi, rewrite_syntax)
artifactPolicy	no	Cache policy for fetched mods (reuse, rebuild, clean_rebuild)

Validation phases: structural parse in ProjectManifest build, then graph validation for mod topology (E1801–E1899 band).

Application host and app target

Hosted applications use the app executable target. The entry module must perform exactly one launch SomeHost(...) per run. Lib projects may declare reusable host types but must not use launch.

Template project type (Template)

Optional nested block:

project {
  type = Template
  template {
    shortName = "console"
    identity  = "beskid.templates.console"
  }
}

Authoritative engine manifest: .beskid/template.json (beskid.template.v1). See Template packages.

Implementation anchors

• Parse + validation: compiler/crates/beskid_analysis/src/projects/parser.rs, validator.rs
• Manifest resolve: compiler/crates/beskid_analysis/src/projects/manifest_resolve.rs
• Graph + plan: compiler/crates/beskid_analysis/src/projects/graph/, compile_plan.rs
• Pack profile: compiler/crates/beskid_pckg/src/pack.rs