agentic-domain-artifact

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.0 기준으로 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 포함 | | Seed apply handler | sampleExecution placeholder artifact 등록 포함 | | Fixture | Business Process Definition 예시 포함 | | Validator | 후속 iteration | | Agent contribution | 후속 iteration | | CLI | 1차 구현 제외 | | Adapter | 1차 구현 제외 |

도메인 책임

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

제외 범위

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

기본 API 예시

import {
  ArtifactService,
  initializeArtifactDatabase,
  openArtifactDatabase,
  getArtifactPackageInfo
} from "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는 agentic-domain-document의 reader/service가 해석합니다.

Sample Execution Seed Apply 예시

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

import { applyAgenticSeed } from "agentic-domain-artifact";

await applyAgenticSeed({
  sourcePackageName: "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를 관리합니다.