@trama-chain/core

Trama 모델의 도메인 계층 — 문서 스키마 · 파싱 · 결정론적 실행.

React·DOM·zustand에 의존하지 않는다. 브라우저 편집기(projector-web)와 정적 뷰어 (projector-static)가 이 패키지 위에 얹히고, Node 환경(서버 워커·CLI·LLM 파이프라인)은 이 패키지만 단독으로 쓸 수 있다.

설치

pnpm add @trama-chain/core

런타임 의존은 zod 하나다.

진입점

배럴(.)은 실행·생성기·단위 카탈로그까지 전부 끌어온다. 문서를 읽고 검증만 하는 호스트는 좁은 진입점을 쓰는 편이 낫다.

| 진입점 | 내용 | |---|---| | @trama-chain/core | 전체 배럴 — 모델·실행·스키마·레지스트리 | | @trama-chain/core/schema | 문서 스키마 · 파싱 · 직렬화 · Model↔Document 변환. 런타임 의존은 zod 뿐 | | @trama-chain/core/model | 모델 타입과 조작 연산 | | @trama-chain/core/execution | 시뮬레이션 실행·전파·스냅샷 캡처 | | @trama-chain/core/functions · /combiners | shape · combiner 레지스트리 | | @trama-chain/core/units · /history | 단위 카탈로그 · 편집 이력 | | @trama-chain/core/validate | 문서 검증 — 진단 목록을 돌려준다. 디스크립터를 쓰므로 /schema만큼 가볍지는 않다 | | @trama-chain/core/spec | LLM 프롬프트용 문서 명세. 어휘에서 파생 생성된다 |

문서 읽기

import { parseTrama, documentToModel } from '@trama-chain/core/schema';

const doc = parseTrama(jsonString);   // 실패 시 TramaParseError
const model = documentToModel(doc);

parseTrama는 zod 스키마 검증과 lag=0 즉시 사이클 검사를 수행한다. shape·combiner 키까지 확인하려면 레지스트리를 넘긴다:

import { createDefaultShapeRegistry, createDefaultCombinerRegistry } from '@trama-chain/core';

parseTrama(jsonString, {
  shapeRegistry: createDefaultShapeRegistry(),
  combinerRegistry: createDefaultCombinerRegistry(),
});

마크다운 본문에 임베드된 문서는 첫 ```trama 펜스에서 꺼낸다:

import { extractAndParseTramaFromMarkdown } from '@trama-chain/core/schema';

실행

import { executeModel } from '@trama-chain/core/execution';
import { createDefaultShapeRegistry } from '@trama-chain/core/functions';
import { createDefaultCombinerRegistry } from '@trama-chain/core/combiners';

const trajectory = executeModel(model, {
  shapeRegistry: createDefaultShapeRegistry(),
  combinerRegistry: createDefaultCombinerRegistry(),
});

스텝 수는 model.execution.steps를 따르고, 반환값은 초기 상태를 포함한 상태 배열이다. LaTeX 식 노드를 쓰는 모델은 expressionEvaluator를 함께 넘겨야 식이 평가된다.

같은 모델·같은 seed면 항상 같은 결과가 나온다. 생성기의 난수는 모델에 영속되는 seed로 재현된다.

검증

parseTrama는 첫 실패에서 throw한다. 생성된 문서를 고쳐 쓰게 하려면 무엇이 몇 개 어떻게 틀렸는지 한 번에 필요하다.

import { validateTrama, hasErrors, formatDiagnostics } from '@trama-chain/core/validate';

const diagnostics = validateTrama(doc);
if (hasErrors(diagnostics)) {
  console.error(formatDiagnostics(diagnostics));
}

없는 노드를 가리키는 엣지, 중복 id, 슬롯 범위, 포트 종류 불일치, 미등록 단위·상수·shape, 피드백 대상 적격성을 error로 잡고, 좌표 없음·focal 부재·고립 노드·과도한 steps를 warning으로 낸다. skin과 visualization은 렌더러 소유 어휘라 허용 목록을 넘길 때만 검사한다.

명세

import { buildTramaSpec, SPEC_EXAMPLES, specSize } from '@trama-chain/core/spec';

const prompt = buildTramaSpec();   // 영문 마크다운, 약 2.9k 토큰

표는 스키마와 레지스트리에서 파생된다 — 어휘가 바뀌면 문서가 따라 바뀐다. 예제는 전부 validateTrama 진단 error 0을 통과하는 것이 테스트로 강제된다.

타입 해석

서브경로 타입은 exports 맵의 types 조건으로 노출되며, moduleResolution이 node (node10)인 소비자를 위해 typesVersions 폴백을 함께 제공한다. 가능하면 호스트 tsconfig를 bundler 또는 node16으로 두는 편이 낫다.

라이선스

MIT