@soddong/agentic-domain-artifact

@soddong/agentic-domain-artifact는 Agentic Platform의 실제 산출물 instance 도메인 패키지입니다.

이 패키지는 산출물 표준을 기반으로 실행 프로젝트에서 생성되는 산출물 instance, component instance, document/file/resource 연결, trace 관계, validation result reference, review decision reference를 소유합니다.

현재 범위

Iteration 0에서는 패키지 skeleton과 Continuous Publish/Delivery 기반을 제공했습니다. 현재는 0.7.4 기준으로 SQLite schema, repository/service, Business Process Definition fixture, Handoff resolve API, review decision reference, lifecycle status event, Activity output 기반 artifact 조립 helper, document binding helper, sampleExecution seed apply handler, schema generated docs를 제공합니다.

| 구분 | 상태 | | --- | --- | | 패키지 skeleton | 포함 | | 기본 문서 | 포함 | | build/typecheck | 포함 | | 최소 public API | 포함 | | Artifact DB migration | 포함 | | Repository/Service | 포함 | | Handoff resolve API | Handoff 계약에 필요한 artifact instance/component/resource/result ref 해석 포함 | | Review decision reference | 검토/승인 결정 외부 참조 포함 | | Lifecycle transition | artifact instance 상태 전이와 status event 이력 포함 | | Activity output assembly | methodology Activity output DTO 기반 artifact/component/resource/trace 생성 helper 포함 | | Document binding helper | ADoc documentId를 component primary DOCUMENT_ID resource로 연결하는 helper 포함 | | Artifact path policy | 실제 산출물 파일 경로/파일명 built-in default와 resolver 포함 | | Seed apply handler | sampleExecution placeholder artifact 등록 포함 | | Fixture | Business Process Definition 예시 포함 | | Validator | 후속 iteration | | Agent contribution | 후속 iteration | | CLI | 1차 구현 제외 | | Adapter | 1차 구현 제외 |

도메인 책임

@soddong/agentic-domain-artifact
  - Artifact Instance
  - Artifact Component Instance
  - Artifact Resource Link
  - Artifact Trace Link
  - Artifact Validation Result Reference
  - Artifact Review Decision Reference
  - Artifact Status Event
  - Artifact status
  - Artifact document binding
  - Artifact review/approval lifecycle
  - Artifact trace
  - Artifact output metadata
  - Sample execution placeholder

제외 범위

| 제외 항목 | 담당 후보 | | --- | --- | | 산출물 표준 정의 | @soddong/agentic-domain-artifact-standard | | Document 저장 구조 | @soddong/agentic-domain-document | | Methodology Activity/Stage 요구 관계 | @soddong/agentic-domain-methodology | | 검증 실행 엔진 | @soddong/agentic-capability-validation | | Render 실행 | @soddong/agentic-capability-render |

기본 API 예시

import {
  ArtifactService,
  initializeArtifactDatabase,
  openArtifactDatabase,
  getArtifactPackageInfo
} from "@soddong/agentic-domain-artifact";

console.log(getArtifactPackageInfo());

const init = initializeArtifactDatabase({ projectRoot: process.cwd() });
console.log(init.tables);

const db = openArtifactDatabase({ projectRoot: process.cwd() });
const service = new ArtifactService(db);

const artifact = service.createArtifactInstance({
  artifactCode: "component-a-business-process-definition",
  artifactName: "A컴포넌트 비즈니스 프로세스 정의서",
  artifactStandardCode: "business_process_definition",
  artifactStandardVersion: "1.0.0"
});

const appendix = service.addArtifactComponentInstance({
  artifactInstanceId: artifact.artifactInstanceId,
  artifactComponentCode: "appendix_l3_process",
  artifactComponentRoleCode: "APPENDIX",
  componentInstanceName: "A컴포넌트 L3 프로세스 부록"
});

service.addArtifactResourceLink({
  artifactInstanceId: artifact.artifactInstanceId,
  artifactComponentInstanceId: appendix.artifactComponentInstanceId,
  resourceTypeCode: "DOCUMENT_ID",
  resourceRef: "adoc-document-id-for-appendix-l3-process",
  isPrimary: true
});

service.addArtifactReviewDecisionRef({
  artifactInstanceId: artifact.artifactInstanceId,
  reviewScopeCode: "artifact_instance",
  decisionCode: "approved",
  reviewerRef: "user://reviewer",
  decisionReason: "후행 Stage 전달을 승인한다.",
  decisionResultRef: "execution://review/component-a-business-process-definition/0.1.0"
});

const aggregate = service.getArtifactAggregate(artifact.artifactInstanceId);
console.log(aggregate.components);

db.close();

Activity Output 기반 조립 예시

artifact는 methodology 패키지를 직접 의존하지 않습니다. runtime/application layer가 methodology Activity output을 중립 DTO로 변환해 전달하면, artifact는 실제 artifact instance, component instance, resource link, trace link를 생성합니다.

const created = service.createArtifactInstanceFromActivityOutputs({
  artifact: {
    artifactCode: "component-a-business-process-definition",
    artifactName: "A컴포넌트 비즈니스 프로세스 정의서",
    artifactStandardCode: "business_process_definition",
    artifactStandardVersion: "1.0.0"
  },
  activityOutputs: [
    {
      sourceRefId: "methodology-activity-output-main",
      artifactComponentCode: "main_document",
      artifactComponentRoleCode: "MAIN",
      componentInstanceName: "본문",
      resource: {
        resourceTypeCode: "DOCUMENT_ID",
        resourceRef: "adoc-document-id-main",
        isPrimary: true
      }
    },
    {
      sourceRefId: "methodology-activity-output-l3",
      artifactComponentCode: "appendix_l3_process",
      artifactComponentRoleCode: "APPENDIX",
      componentInstanceName: "L3 프로세스 부록",
      resource: {
        resourceTypeCode: "DOCUMENT_ID",
        resourceRef: "adoc-document-id-l3",
        isPrimary: true
      }
    }
  ]
});

console.log(created.aggregate.components);
console.log(created.aggregate.traceLinks);

기존 component에 ADoc document를 나중에 연결해야 하는 경우에는 bindDocumentToArtifactComponent()를 사용합니다.

service.bindDocumentToArtifactComponent({
  artifactInstanceId: created.artifact.artifactInstanceId,
  artifactComponentInstanceId: created.components[0].artifactComponentInstanceId,
  documentId: "adoc-document-id-main",
  metadata: {
    documentProfileCode: "business_process_definition.main_document"
  }
});

Handoff Resolve API 예시

artifact는 methodology가 정의한 Handoff Requirement 자체를 소유하지 않습니다. 대신 runtime/application 계층이 Handoff Requirement에서 필요한 값을 중립 DTO로 변환해 전달하면, artifact는 실제 artifact instance, component instance, resource link, validation result reference, review decision reference를 해석합니다.

const handoff = service.resolveArtifactHandoff({
  artifactStandardCode: "business_process_definition",
  artifactStandardVersion: "1.0.0",
  requiredComponentCodes: [
    "main_document",
    "appendix_l3_process",
    "appendix_scenario",
    "appendix_l4_detail"
  ],
  requiredResultRefs: [
    "validation_result",
    "review_decision"
  ],
  requiredResourceTypeCode: "DOCUMENT_ID"
});

if (!handoff.resolved) {
  console.log(handoff.missing);
}

이 API는 document 본문을 조회하지 않습니다. 반환된 DOCUMENT_ID resource는 @soddong/agentic-domain-document의 reader/service가 해석합니다.

Artifact Path Policy

artifact는 Seed/Bundle이 명시적인 physical structure policy를 제공하지 않아도 실제 산출물 파일 경로를 계산할 수 있는 built-in default를 제공한다.

기본 정책은 다음이다.

pathPattern   = artifacts/{projectCode}/{phaseCode}/{stageCode}
namingPattern = {artifactStandardName}.md

예:

artifacts/nova-bil-cal-core-sdd-v2/build_planning_phase/analysis_stage/선행 산출물 입력 기준선 정의서.md

정책 우선순위는 다음과 같다.

1. Execution Project override
2. Seed/Bundle 또는 Artifact Standard physicalStructurePolicy
3. DEFAULT_ARTIFACT_PATH_POLICY

사용 예:

import { resolveArtifactOutputPath } from "@soddong/agentic-domain-artifact";

const path = resolveArtifactOutputPath({
  projectCode: "nova-bil-cal-core-sdd-v2",
  methodologyCode: "ai_agent_sdlc",
  phaseCode: "build_planning_phase",
  stageCode: "analysis_stage",
  activityCode: "define_prior_input_baseline",
  artifactStandardCode: "prior_input_baseline_definition",
  artifactStandardName: "선행 산출물 입력 기준선 정의서"
});

console.log(path.relativePath);

artifactStandardName 기반 파일명은 사용자 친화성을 위한 표시 경로다. DB trace와 handoff, validation, generated output link는 반드시 artifactStandardCode와 artifactInstanceId 같은 안정 식별자를 사용한다.

fileNamePolicy.stableIdentifier를 지정하면 resolver 결과의 stableIdentifier 기준을 바꿀 수 있다. 지원 placeholder에 없는 값이 pattern에 남으면 잘못된 파일 경로를 만들지 않고 오류로 처리한다.

Windows 호환성을 위해 파일명 금지 문자와 예약어는 resolver가 sanitize한다. 동일 경로에 같은 파일명이 존재하는 경우 fallback은 다음 순서로 적용한다.

1. {artifactStandardName}.md
2. {artifactStandardName}-{artifactStandardCode}.md
3. {artifactStandardName}-{artifactInstanceId}.md

Sample Execution Seed Apply 예시

AI-Agent SDLC seed bundle의 sampleExecution은 실제 산출물 본문이 아니라 seed 적용 가능성을 검증하는 최소 실행 placeholder입니다. artifact는 이를 sample_execution 표준을 가진 artifact instance로 등록하고, 방법론/프로세스/프로젝트 참조를 trace link로 보존합니다.

import { applyAgenticSeed } from "@soddong/agentic-domain-artifact";

await applyAgenticSeed({
  sourcePackageName: "@soddong/agentic-methodology-ai-agent-sdlc",
  sourcePackageVersion: "0.2.0",
  bundleCode: "ai-agent-sdlc-build-planning",
  bundleVersion: "0.2.0",
  methodologyCode: "ai_agent_sdlc",
  sourceSection: "sampleExecution",
  targetOperation: "prepare_sample_execution",
  itemKey: "ai_agent_sdlc_build_planning_minimal_sample",
  mode: "apply",
  itemPayload: {
    sampleCode: "ai_agent_sdlc_build_planning_minimal_sample",
    methodologyCode: "ai_agent_sdlc",
    lifecycleCode: "incremental_build_lifecycle",
    phaseCode: "build_planning_phase",
    processCode: "build_planning_process",
    projectCode: "sample-ai-agent-sdlc-build-planning-project"
  }
});

모듈 경계

artifact는 실제 산출물 instance를 관리합니다. 산출물 표준의 본문/부록 구조는 artifact-standard가 정의하고, 실제 document 본문 저장은 document가 담당합니다.

artifact-standard
  [email protected]
    DocumentComponent: appendix_l3_process

methodology
  Activity output:
    artifactStandardCode: business_process_definition
    artifactComponentCode: appendix_l3_process

artifact
  ArtifactInstance:
    [email protected]
  ArtifactComponentInstance:
    main_document
    appendix_l3_process
    appendix_scenario
    appendix_l4_detail
  ArtifactResourceLink:
    DOCUMENT_ID adoc-document-id-for-each-component
  ArtifactTraceLink:
    produced_by methodology_activity_artifact_requirement

최신 조립 기준에서는 하나의 Stage 안에서 산출물 구성 요소별 Activity output을 생성하고, artifact가 각 output에 대응하는 component instance, DOCUMENT_ID resource link, trace link를 관리합니다.