Plugin SDK 개발·검증·릴리스 — Altifigence Documentation

개발·검증·릴리스 도구와 1.2 워크플로·증분 cache·외부 도구·공개 LSP 브리지를 확인하세요.

DDS Plugin SDK 1.2.0의 개발·검증·릴리스 가이드입니다. 보안 감사·취약점 검증은 대기 중이며 안정 API와 기능 검증을 보안 통과로 해석하지 마세요.

개발 템플릿과 계약 생성

command·language·theme·job·browser·configuration 중 하나를 선택합니다. init --dry-run은 쓰기·설치 없이 목적지·파일 목록·해시·충돌을 보여 줍니다. 실제 init에는 새 실제 디렉터리가 필요합니다. 각 템플릿에 소스·manifest·고지·라이선스·테스트·타입 소비자·실행 예제를 포함하며 browser와 configuration에는 loopback 데모를 제공합니다. 의존성은 정확한 GitHub archive에 고정됩니다.

npx --no-install dds-plugin init example-plugin --template configuration --dry-run
npx --no-install dds-plugin init example-plugin --template configuration
cd example-plugin
npm install --ignore-scripts
npm run doctor
npm test
npm run typecheck
npm run example
npm run browser

dds-dev.json은 명령 스키마·설정·카탈로그·테마를 담는 제한된 JSON 데이터입니다. generate는 런타임 JSON·ESM·원시/검증 입력 타입·출력/설정 타입·JSON Schema·테마 XML을 생성합니다. JSON Schema default는 주석이며 SDK 입력 검증이 기본값을 적용합니다. 생성 중 플러그인을 import하지 않습니다. doctor는 drift·metadata·누락 모듈과 생성된 런타임 파일의 배포 allowlist 포함 여부를 확인합니다.

npx --no-install dds-plugin generate . --check
npx --no-install dds-plugin generate . --dry-run
# Review the new files, then use the previous digest from the report:
npx --no-install dds-plugin generate . --expected-digest <previous-digest>

교체에는 이전 digest와 변경되지 않은 생성 바이트가 필요합니다. 수동 편집·추가 파일·링크·남은 잠금은 교체를 중지합니다. 실패한 시도는 자신이 만든 변경 없는 항목만 제거하고 수정되거나 소유가 불확실한 항목을 보존합니다. 파일 256개·각 1MiB·합계 4MiB를 제한합니다. 잠금은 협력하는 생성기를 조정하며 적대적 동시 쓰기 방어나 디렉터리 간 원자적 트랜잭션을 보장하지 않습니다. 비공개 템플릿은 사용자가 제공한 약관을 요구하며 상속한 SDK 라이선스·고지를 보존합니다.

결정적 테스트와 재생

/testing의 createScenarioHost는 선택한 메모리 파일·backend·설정·비밀·작업 fixture만 연결하며 기본 권한·capability는 없습니다. createTestClock은 전역 수정 없이 seed 기반 ID·시간·타이머를 공급하고 같은 시각의 타이머는 삽입 순서를 유지합니다. 가상 대기는 clock 진행을 await해 해제합니다. 생성 UUID는 테스트 데이터이며 암호학적 난수가 아닙니다. 기존 createTestHost 기본 동작은 유지합니다.

import {createScenarioHost} from '@altifigence/dds-plugin-sdk/testing';
const scenario = createScenarioHost({seed: 7, start: 1000,
  files: {'example.txt': 'synthetic'}, grants: ['workspace.read'],
});
try {
  // Activate your explicitly imported test plugin on scenario.host.
  scenario.faults.enqueue({operation: 'file.read', kind: 'delay', delayMs: 25});
  // Start its command, then await scenario.clock.advance(25).
} finally {
  await scenario.dispose();
  scenario.assertClean();
}

장애 포트로 지연·거절·연결 해제·손상·고갈·호출 유실을 재현합니다. 이벤트 fixture의 유실·중복·역순은 외부 효과를 재실행하지 않습니다. replaceGrants는 권한을 잃은 플러그인을 비활성화합니다. 메모리 작업 snapshot은 identity·revision·해시를 검증하며 자동 실행 없이 interrupted 복구를 재현합니다. 파일시스템 내구성이나 OS 핸들 발견을 대신하지 않으며 별도 소유자 ledger가 명시적으로 등록한 자원을 추적합니다. 취소를 무시한 callback은 실제 종료까지 pending에 남습니다. 설정 inspect는 종료 후에도 조회되지만 데이터 읽기는 거부합니다.

기록에는 synthetic: true와 명시한 제한된 fixture 목록이 필요합니다. 내보낸 trace는 작업 종류·fixture ID·시각·seed/version·연결 해시만 포함합니다. 민감하지 않은 ID를 사용하세요. 추측 가능한 값의 해시는 익명화가 아니며 SDK가 임의 입력의 합성 여부를 판별하지 않습니다. 순수 재생은 순서·해시·fixture identity를 검사하고 지정 출력만 반환하며 효과 callback을 받지 않습니다. fixture 64개·이벤트 1,024개·trace 1MiB를 제한합니다. 배포된 development-tools 예제에서 장애·복구·비노출·정리를 확인할 수 있습니다.

로컬 진단과 디버깅

import {createDiagnosticSession, profileHost}
  from '@altifigence/dds-plugin-sdk/diagnostics';
const session = createDiagnosticSession({enabled: true, sampleEvery: 10});
const measured = profileHost(host, session);
try {
  await measured.executeCommand('example', 'run', {});
} finally {
  measured.dispose();
  console.log(session.snapshot());
  session.dispose();
}

진단은 기본 비활성이고 로컬에서만 동작합니다. 보고서는 고정 작업·상태·오류 코드·상관 ID·시간·자원 수를 담으며 문서 본문·경로·입력·출력 본문·임의 예외 문구를 받는 API가 없습니다. 바이트·큐 깊이·메모리 값은 소유자가 명시한 추정치입니다. profileTransport는 호출 반환까지 측정하므로 fetch는 본문 종료가 아닌 응답 헤더까지입니다. 완료 기록은 제한된 ring과 수동 조회 시 만료를 사용하며 진단용 백그라운드 타이머·업로드는 없습니다. 기본 128개·60초, 최대 256개·5분·동시 span 64개·보고서 256KiB를 적용합니다.

npx --no-install dds-plugin dev . --trust-local-code --profile --command greet --input '{"name":"Ada"}'
npx --no-install dds-plugin dev . --trust-local-code --debug --debug-wait --timeout-ms 30000 --command greet --input '{"name":"Ada"}'

debug는 소유한 자식 프로세스의 임시 127.0.0.1 inspector만 노출합니다. --debug-wait는 플러그인 import 전 대기하며 --debug가 필요합니다. 전체 실행 예산은 디버거 대기를 포함해 최대 30초입니다. 완료·취소·시간 초과 때 소유한 자식과 inspector를 종료합니다. profile과 debug 모두 로컬 코드의 명시적 신뢰를 요구하며 sandbox가 아닙니다. 충돌·강제 종료 때 보고서가 없을 수 있고 원시 stdout/stderr는 자동 정제하지 않는 별도 제한 스트림입니다.

Development tools · Testing · Diagnostics · Compatibility

호스트 적합성 검사

/conformance는 명시한 호스트·설정·workspace·번역·테스트·진단·개발 어댑터에 버전이 있는 합성 검사를 실행합니다. supported·unsupported·failed를 구분하고 호스트/버전/런타임/플랫폼·검사 ID·시간·정리 상태를 제공합니다. 지원한다고 선언했지만 어댑터가 없거나 잘못되면 실패하며, 모르는 선택 기능은 호출 없이 기록합니다. 명령·권한·취소가 기본 필수 검사입니다.

import {runConformance, formatConformanceReport}
  from '@altifigence/dds-plugin-sdk/conformance';
import {createPluginHost} from '@altifigence/dds-plugin-sdk';
const report = await runConformance({
  identity: {host: 'My host', version: '1.0.0', runtime: 'Node 24', platform: 'linux-x64'},
  features: ['commands', 'permissions', 'cancellation'],
  adapters: {host: options => createPluginHost(options)},
});
console.log(formatConformanceReport(report));

호스트 factory를 자신의 어댑터로 교체하고 플러그인 테스트도 실행하세요. Node /conformance-node helper는 새 임시 fixture와 임시 loopback 서버만 만듭니다. 브라우저 예제는 사용 가능한 프로필을 실행하고 없는 Node 기능을 unsupported로 표시합니다. 빠른 검사는 계약을 표본 검사하며 연결된 예제·릴리스 테스트가 더 큰 언어·복구·저장 경로를 검증합니다. 보고서는 테스트 근거이며 신뢰 인증서가 아닙니다.

사례별 기본 기한은 10초, 최대 30초입니다. 시간 초과·취소는 이후 검사를 중지하고 정리 실패는 사례를 실패시킵니다. pending 정리는 완료가 검증되지 않은 상태입니다. 신뢰한 프로세스 내부 어댑터는 동기 작업을 차단할 수 있고 프로세스 권한을 가집니다. 보고서에서 제공자 오류 본문·payload·token·경로를 제외하며 identity label도 민감하지 않은 값으로 지정하세요. 자동 업로드는 없습니다.

SDK 지원과 이전

API_SUPPORT.json은 모든 export·런타임 이름·선언·선언 digest·환경·안정성을 나열합니다. 안정화된 1.x API는 semantic versioning을 따르며 호환 추가는 minor, 비호환 변경은 새 major로 제공합니다. artifact-resume-browser는 실험 기능으로 유지하고 정확한 SDK/브라우저 버전과 새 브라우저 수용 검증이 필요합니다. 선택 capability 확인과 현재 권한 검사는 계속 필요합니다.

안정 버전 정책은 1.0.0부터 적용됩니다. 최신 stable minor는 일반 수정을 받고 직전 minor는 지원 런타임 안에서 후속 발행 후 90일간 중대한 보안 수정 대상입니다. 1.0.0에서 deprecated인 stable API는 없습니다. 폐기는 적어도 두 minor와 6개월간 고지한 뒤 새 major에서 제거합니다. RC와 preview는 후속 버전으로 대체하며 상용 응답 시간은 보장하지 않습니다.

서버·CLI 수용 검증은 Windows/Linux와 보안 패치한 Node 22/24, 타입 선언은 TypeScript 5.9.3을 대상으로 합니다. Node 22 지원 종료는 2027-04-30, Node 24는 2028-04-30입니다. 릴리스 근거에 정확한 패치·OS 이미지·브라우저 빌드를 기록합니다. 다른 런타임·브라우저/저장소 조합은 별도 검증이 필요하며 SDK 런타임 npm 의존성은 없습니다.

안정 1.0 플러그인은 >=1.0.0 <2.0.0을 사용하고 이후 API를 쓰면 최저 버전을 높입니다. RC1 패키지는 정확한 1.0.0-rc.1 peer를 유지합니다. 변경하려면 재검증한 새 버전을 발행하고 기존 archive는 보존하세요. 이전 archive는 상호 운용성 입력이며 유지보수 계열은 아닙니다. 재시작 뒤 새 연결·현재 권한을 확보하고 확정 상태만 조회하며 자동 재실행하지 않습니다.

릴리스 수용 검증

보안 감사와 취약점 검증은 소유자의 2026-10-05 결정에 따라 대기 중입니다. 기능·호환성·성능 결과가 보안 수용을 의미하지 않습니다. 보존한 검토는 별도로 재개하며 이번 릴리스가 해당 감사를 통과했다고 해석해서는 안 됩니다.

복합 fixture는 언어/설정·검토한 편집·명령 작업·프로젝트 감시·업로드/다운로드·보관 저장소를 동시에 실행합니다. 연결 중단·잘못된 응답·권한 철회·세대 변경·복구·자원 정리를 검사합니다. 별도 파일시스템/프로세스 테스트로 자식 프로세스 강제 종료·손상·쓰기 실패·만료·취소 무시를 검증합니다. RC 수용 보고서에서 재현 명령과 각 결과의 범위를 확인하세요.

성능 기록은 Windows/Linux와 Node 22/24 각 프로필에서 새 프로세스 5회의 중앙값·분산, CPU 시간·표본 메모리·import/시작/감시 시간과 논리 디스크/HTTP payload 양을 측정합니다. 기준값은 그 실측에서 산출한 큰 회귀 탐지용이며 응답 시간 보장이 아닙니다. 물리 디스크 트래픽을 측정하거나 모든 OS handle 발견을 보장하지 않습니다.

npm ci --ignore-scripts
npm run check
npm run example:conformance -- --json
npm run example:combined -- --faults
npm run benchmark:combined
npm run example:conformance-browser

Conformance · API inventory · Support policy · RC acceptance

1.0 정식 릴리스 구성

원래 1.0 배포물은 38개 export·86개 schema·타입·예제·LICENSE/NOTICE를 포함합니다. 1.1은 아래 릴리스 도구를 추가하며 1.2는 아래의 워크플로/캐시/도구/LSP를 추가합니다. 릴리스 자료는 정확한 소스/CI·digest·독립 소비자와 재사용한 브라우저 증거를 구분합니다.

되돌리기에는 소유한 작업을 중지한 뒤 보관한 호환 SDK·플러그인 archive와 설정 export를 명시적으로 선택합니다. 현재 권한과 새 연결을 확인하세요. 결과 복구는 조회이며 외부 효과나 비호환 설정을 자동으로 되돌리지 않습니다. 사용한 형식과 선택 기능에 맞게 downgrade를 검증하세요.

릴리스 구성·이전·지원 안내

오프라인 번들과 SBOM

SDK 1.1은 선택적인 Node 전용 /bundles·/provenance·/updates·/updates-node·/upstream을 추가합니다. 배포물은 43개 export·96개 schema·타입과 실행 예제를 포함하며 런타임 npm 의존성은 없습니다. 기존 1.0 API와 unsigned DDS .tgz archive 호환은 유지합니다.

lockBundleDependency는 검토한 ESM/CommonJS 파일 트리를 정확한 버전·HTTPS 출처·파일 digest·의존성 map·LICENSE/NOTICE와 명시적인 재배포 판단에 묶습니다. digest는 검토한 파일 트리의 값이며 upstream archive 해시와는 다릅니다. createPluginBundle은 원래 DDS plugin archive·release metadata·버전이 하나로 고정된 비순환 graph와 결정적 CycloneDX 1.6 SBOM을 함께 담습니다.

verifyPluginBundle은 제한된 정확한 바이트 snapshot을 검사합니다. installPluginBundle에는 expectedSha256·approved: true·운영자가 소유한 부모 아래 새 디렉터리가 필요합니다. npm·lifecycle script·다운로드·plugin code를 실행하지 않으며 의존성에 새 grants를 상속하지 않습니다. 호스트 SDK는 별도 의존성입니다. native addon·export map·임의 npm 의존성 해석은 이 형식의 범위 밖입니다.

한도는 의존성 32개·펼친 파일 1,024개·의존성 파일당 4 MiB·펼친 내용 32 MiB·인코딩 bundle 48 MiB입니다. 원래 root archive에는 별도의 더 작은 한도가 적용됩니다. 누락/충돌 버전·순환·사용하지 않는 의존성·변경 해시·LICENSE/NOTICE 누락·경로/링크·파일/디렉터리 충돌을 거부합니다. 설치 실패 시 새 목적지를 검사할 수 있도록 남깁니다. 동시 파일 쓰기를 배제해야 하며 OS sandbox는 아닙니다.

분리 서명과 운영자 신뢰

createProvenanceStatement는 정확한 bundle 이름/버전/SHA-256·발행자·소스 revision·발행/만료 시각을 묶습니다. signPluginProvenance는 호출자가 소유한 Ed25519 KeyObject를 사용합니다. canonicalProvenancePayload는 DDS-PROVENANCE-V1과 canonical JSON을 제공해 다른 signer도 동일한 payload를 만들게 합니다. SDK는 private signing key나 DDS 제품 서명 권한을 제공하지 않습니다.

verifyPluginProvenance에는 운영자가 선택한 trust root·발행자/대상 연결·현재 시각·키 유효기간/폐기와 관측 시각이 있는 폐기 자료를 제공합니다. 오프라인 검증도 제공된 자료에 같은 freshness 한도를 적용하며 최신 폐기 정보를 직접 가져오지 않습니다. 패키지가 새 키를 선언해도 운영자가 추가하기 전에는 신뢰하지 않습니다. 명시적인 두 root의 중첩으로 키를 교체할 수 있습니다. 시각 오차는 최대 5분, 자료 나이는 최대 30일이며 더 엄격한 값을 선택할 수 있습니다.

receipt는 checksum·signature·publisher·policy를 구분하고 executionAuthorized: false를 반환합니다. 서명이 코드의 안전성을 증명하거나 실행·데이터 접근·sandbox 권한을 부여하지 않습니다. 이전 unsigned 패키지는 envelope: null·allowUnsigned: true가 필요하며 계속 unsigned·unverified publisher로 표시합니다. 보안 감사·취약점 검증은 별도로 대기 중입니다.

검토·활성화·롤백

createPluginUpdatePlan은 이전/새 버전·API·grants·의존성 출처/해시·선언 도구·라이선스·설정 해시·migration 식별자·서명/키를 비교하고 검토 digest를 고정합니다. createPluginUpdateController는 현재 승인된 호스트·설정과 운영자의 getPolicy/prepare 포트를 사용합니다. stage는 후보를 검사해 snapshot으로 보관하고 approve는 정확한 plan digest·grants·key ID와 일치해야 합니다. activate는 현재 설정을 확인하고 별도 후보 호스트를 준비하기 전후에 신뢰를 다시 확인합니다.

wait는 실행 중 작업이 있으면 활성화를 미룹니다. retain-old는 기존 작업을 원래 호스트/설정/해시에 유지하고 교체 후 새 실행을 새 호스트로 보냅니다. execute는 결과와 plugin 해시를 함께 반환하며 작업을 임의로 취소하지 않습니다. 설정 교체는 대기 승인을 무효화하고 동시 변경·준비 실패는 기존 상태를 보존하거나 정확히 보고합니다. 롤백은 이전 패키지/설정을 새 검토 대상으로 stage하고 현재 신뢰와 새 승인을 요구합니다.

준비와 migration은 운영자가 소유한 신뢰된 포트에서 실행합니다. 롤백이나 실패가 외부 파일·네트워크 요청·다른 부작용을 되돌리지는 않습니다. reversible은 검토 metadata이며 자동 undo 보장이 아닙니다. Node journal은 workspace 밖에서 단일 writer·append-only·정확한 revision CAS를 사용하며 한도는 256개 record / envelope당 128 KiB / 합계 8 MiB입니다. 한도에 도달하면 운영자가 보관한 뒤 새 journal을 시작합니다.

inspectNodeUpdateJournal은 저장 상태만 조회하고 재실행하지 않습니다. preparing 중 종료되거나 응답이 불확실하면 호스트/설정을 명시적으로 재조회해야 합니다. reconcilePluginUpdateJournal은 승인한 알려진 이전/새 digest와 설정 해시를 기록합니다. 손상된 끝부분은 운영자가 검사·복구해야 합니다. recoverStaleLock은 같은 머신에서 종료가 입증된 writer만 복구합니다. 프로세스 전체의 호스트/설정 트랜잭션이나 모든 환경의 전원 장애 원자성을 보장하지 않습니다.

명시적인 Upstream 점검과 후보

fetchUpstreamArtifact에는 명시적인 호출·enabled: true·정확한 URL/버전/digest·정확한 URL allowlist·오프라인 정책·바이트 한도·기한이 필요합니다. 리다이렉트 목적지도 허용 목록에 있어야 합니다. 쿠키/인증 헤더를 보내거나 자동 재시도하지 않으며 관측 시각과 verified / digest-mismatch / unavailable / offline / unverified를 반환합니다. 태그나 해시가 바뀌면 새 검토가 필요하고 loopback HTTP는 명시적 fixture 옵션으로만 사용할 수 있습니다.

adapter는 API 목록·정확한 source revision·전체 LICENSE/NOTICE·파일 해시를 포함한 검토된 upstream-manifest를 발행할 수 있습니다. inspectUpstreamManifest는 그 metadata를 다운로드 바이트에 연결하며 임의 소스를 분석하거나 재배포 권한을 추론하지 않습니다. createUpstreamCandidate는 API/파일/라이선스 차이와 이전 digest/새 source patch를 반환합니다. 정확한 지원 버전 표에 있어도 개발자 기능 검사가 없으면 unverified이며 필수 API가 없으면 unsupported입니다.

supported 후보도 사람의 검토가 필요하며 automaticActions 배열은 비어 있습니다. API가 branch 생성·merge·publish·새 grants 승인·monitor 설치를 수행하지 않습니다. adapter 기능 검사 실행과 취소는 호스트가 소유합니다. 아래 공개 예제는 로컬 fixture만 사용합니다. 워크플로/캐시/도구/LSP API는 아래 1.2 항목에서 사용할 수 있습니다.

node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjs

타입·API·한도 및 실행 가능한 전체 소스

명령 워크플로와 명시적 복구

SDK 1.2는 선택적인 /workflows·/workflows-node·/workflow-cache·/workflow-cache-node·/tool-streams·/tool-streams-node·/lsp-node export를 추가합니다. 현재 배포물은 50개 export·107개 schema·TypeScript 선언·독립 설치 예제를 포함하고 런타임 npm 의존성은 없습니다. 새 export 중 /tool-streams만 브라우저에서도 사용할 수 있으며 나머지는 Node 전용입니다. 기존 workspace protocol과 1.x API 호환을 유지합니다. 새 1.2 API를 import하는 plugin은 최소 SDK 버전을 1.2.0으로 선언해야 합니다.

prepareWorkflowPlan은 실행 전에 등록 command ID·고유 step·비순환 의존성·닫힌 입력/출력 data schema·필수 출력 연결을 검증합니다. 입력은 {value} 리터럴 또는 명시적 의존 단계의 {step, path}이며 schema 제약은 정확히 일치해야 합니다. 불변 plan은 command·grants·범위·입력을 SHA-256에 묶고 run에는 approved: true와 검토한 정확한 digest가 필요합니다. authorize와 execute port는 운영자가 소유합니다.

createCommandJobExecutor는 resolveHost가 고른 분리된 기존 PluginHost에 연결하며 정확한 host scope·step grants·plugin hash를 확인합니다. 단계 간 grants를 합치지 않고 실행 전·결과 반환 후·재사용 전에 현재 권한을 확인합니다. continue는 독립 분기를 완료하고 실패한 의존 단계의 후속 실행을 막으며 fail-fast는 나머지를 취소합니다. record에는 parent job/attempt·개별 job·입출력 digest·artifact·이유·시각을 남깁니다. cache hit에는 새 job ID가 없고 가변 job artifact를 새 실행처럼 표시할 수 없습니다.

recover는 저장 checkpoint를 읽어 pending/running을 interrupted로 표시하며 실행하지 않습니다. 수동 resume은 정확한 이전 record와 previousAttemptId를 새 승인에 제공하고 새 attempt를 만듭니다. 입력이 일치하고 만료되지 않은 성공 결과만 재사용하며 retrySteps는 선언 순서와 무관하게 선택한 단계와 후속 의존 단계를 다시 실행합니다. 만료 결과는 명시적인 retry 선택이 필요하고 schema·입력·grants·plugin hash가 바뀌면 새 plan이 필요합니다. 취소를 무시하는 executor는 실제 종료까지 unsettled로 남아 중복 재시도를 막습니다.

createNodeWorkflowStore는 실제로 분리된 store/workspace 디렉터리·scope/파일시스템 식별 marker·단일 writer·checksum envelope·CAS checkpoint를 사용합니다. 확인된 장애 뒤 명시적인 recoverStaleLock은 같은 컴퓨터에서 종료가 입증된 owner만 복구합니다. 기본 cleanup은 알려진 손상 record와 미완료 쓰기를 정리하고 알 수 없는 파일/링크를 보존합니다. cleanup({expiredBefore})는 만료된 최종 record도 지울 수 있지만 active record는 복구용으로 남깁니다. Windows의 directory fsync나 전원 장애 내구성을 주장하지 않습니다. 한도는 64단계·동시 8단계·전체 10분·결과당 64 KiB·출력 합계 1 MiB·record 2 MiB·보관 record 64개·부분 결과 보관 최대 24시간입니다.

타입·API·한도와 전체 실행 예제

결정적 캐시와 증분 실행

fingerprintWorkflowInputs는 실제 파일 바이트와 SDK 버전·workspace/security scope·command schema/입력·plugin/tool hash·설정·선언 환경·grants를 함께 해시합니다. 경로와 mtime만으로 내용을 식별하지 않습니다. 운영자가 optIn·deterministic·declaredInputsComplete·secretDependent를 명시하며 미확인/불완전 입력·비결정성·secret 의존·누락/미선언 환경·secret-reference 입력은 이유와 함께 cache를 우회합니다. 호스트는 원문 비밀과 외부 부작용도 제외해야 하며 SDK가 숨은 입력을 추론하지는 않습니다.

createWorkflowCache는 lookup/fill/after-fill/hit/return 시 현재 권한을 다시 확인하고 결과 hash·scope·grants·만료를 검증합니다. 같은 유효 입력의 동시 miss는 한 fill을 공유하고 한 대기자의 취소가 다른 대기자를 취소하지 않습니다. 만료/손상 값은 miss로 처리합니다. TTL/LRU·개수/용량 예산·소유 store cleanup으로 저장량을 제한하며 쓰기 실패는 명시적인 이유가 있는 계산 결과로 남습니다. secret-reference 결과는 저장하지 않습니다. fingerprint 한도는 64파일·파일당 4 MiB·합계 16 MiB이며 cache는 512개·값 합계 16 MiB·동시 fill 8개·fill당 60초입니다.

워크플로 예제는 현재 의존 단계가 성공한 뒤에만 cache를 조회합니다. 파일 변경은 해당 단계를 무효화하고 출력 변경은 의존 단계의 입력 fingerprint를 바꿉니다. 의존 단계 실패 시 기존 후속 cache 조회 전에 실행을 차단합니다. receipt는 hit·miss·shared·bypass와 실제 실행/재사용을 구분하고 cache 지표·저장 바이트·로컬 시간을 제공합니다. 영속 cache는 분리된 owner 디렉터리·원자적 교체·미완료 쓰기/손상 복구를 사용하며 원본 파일을 삭제하지 않습니다.

타입·API·한도와 전체 실행 예제

등록 도구 출력 스트림

createToolStreamParser는 브라우저에서도 동작하는 제한된 UTF-8 JSONL/text decoder입니다. write(bytes, stdout/stderr)를 await해 역압을 적용하고 두 stream이 끝난 뒤 finish합니다. 여러 청크로 나뉜 문자와 마지막 부분 행을 보존하고 log·progress·diagnostic·unknown에 상관 ID를 붙입니다. 잘못된 UTF-8이나 한도 초과는 파싱을 중단합니다. 상대 진단 경로·위치 순서·심각도를 검증하고 소비하는 editor는 현재 문서 내용과도 위치를 대조해야 합니다. createJobToolEventSink는 진행률/로그를 기존 JobReporter로 연결하고 진단은 호출자 sink에 맡깁니다.

선택적인 Node runner에는 운영자가 고정한 backend/tool/version·절대 실행 파일/선택한 구현 파일 pin·정확한 version probe·명시적 환경·닫힌 input schema·필수 scalar argv slot을 등록합니다. 파일 slot은 존재하는 workspace 상대 파일이어야 합니다. plugin 호출은 이미 등록한 tool/version과 검증 입력만 선택하며 shell이나 실행 파일을 고르지 못합니다. 준비/시작 전·이벤트마다·완료 후 현재 권한을 검사하고 receipt에 exit code·취소/실패 이유·출력 통계를 남깁니다.

알려진 한 줄 비밀/경로 리터럴은 청크를 합친 뒤 마스킹하며 인코딩되거나 알려지지 않은 비밀을 자동 탐지하지는 않습니다. runner는 직접 시작한 자식과 pipe만 소유하고 취소/close 시 정리합니다. 다른 세션이나 후손 프로세스 트리를 탐색/종료하지 않으며 OS sandbox가 아닙니다. 한도는 chunk 64 KiB·행 16 KiB·전체 2 MiB·4,096이벤트·대기 쓰기 8개·sink 5초·도구 32개·동시 실행 4개입니다. 별도 5초/16 KiB probe로 설정 버전을 확인합니다.

SDK가 직접 작성한 재배포 가능한 도구 fixture로 UTF-8/JSONL 분할·종료 후 잔여 출력·비정상 exit·취소·한도를 검사합니다. 실제 adapter는 TypeScript 5.9.3의 --noEmit --noLib --pretty false와 임시 intrinsic-type fixture를 사용해 TS2322를 확인합니다. 실행하려면 승인한 기존 TypeScript 설치 경로를 명시합니다. SDK는 외부 도구를 자동 설치/다운로드하지 않고 제공한 hash만으로 발행자를 독립 인증하지도 않습니다.

타입·API·한도와 전체 실행 예제

공개 stdio LSP 브리지

createLspBridge는 명시적으로 승인하고 pin한 stdio 프로세스를 기존 SDK 언어 request/provider에 연결합니다. 지원하는 LSP 3.17 부분집합·UTF-16 위치·전체 snapshot을 협상하고 capabilities에서 광고된 지원과 실제 실행 성공을 구분합니다. completion·hover·definition·references·평면/계층 symbol·signature help·prepare-rename/rename·문서/범위 formatting·code action·전체 semantic token·folding·inlay hint의 15개 SDK 기능을 매핑합니다.

syncDocument와 closeDocument가 didOpen/didChange/didClose를 처리합니다. 현재 version/generation이 바뀌면 오래된 작업을 취소하고 중복 active request ID를 거부하며 늦은 응답을 무시합니다. 로컬 URI는 링크 없이 workspace 안으로 해석되어야 하고 읽기/편집 대상마다 현재 권한과 열린 문서 또는 호스트가 제공한 정확한 snapshot이 필요합니다. rename/format/action 결과는 base hash가 있는 조건부 workspace-edit 제안이며 자동 적용되거나 command가 실행되지 않습니다.

진단은 현재 문서 version이 있어야 수락하고 version 없는/오래된 알림은 버리며 계수합니다. completion resolve/snippet·code-action resolve·semantic delta·server command·dynamic capability·resource operation·socket transport·version 없는 진단은 명시적으로 미지원입니다. workspace/applyEdit는 applied:false를 반환합니다. 한도는 메시지 1 MiB·header 8 KiB·세션 64 MiB/20,000메시지·pending request/대기 쓰기 16개·문서 32개/전체 텍스트 4 MiB·request 최대 30초·버리는 stderr 64 KiB입니다.

close는 shutdown/exit와 제한된 직접 프로세스/pipe 정리를 수행하고 정상 응답·거부/중단·실제 프로세스 종료를 구분합니다. shutdown을 응답했어도 소유 프로세스 중단이 필요할 수 있습니다. 자동 restart/replay는 없으며 운영자가 새 bridge를 만들고 선택한 현재 snapshot을 명시적으로 다시 보냅니다. 합성 서버로 잘못된 framing·crash/timeout·취소/늦은 응답·문서 경합·shutdown 거부·미지원 요청·모든 매핑 기능을 검사합니다.

실제 독립 서버 검사는 community typescript-language-server 5.3.0과 TypeScript 5.9.3을 사용하며 completion·hover·definition·references·symbol·signature help·formatting·semantic token의 8기능이 통과했습니다. 선택한 구현 파일과 Node를 pin하고 tsserver 경로를 고정하며 자동 typings 취득을 끕니다. 이 server 버전은 선택 항목인 initialize.serverInfo를 생략하고 version 없는 진단을 보내므로 해당 진단은 bridge에서 명시적으로 미지원입니다. version 있는 진단은 독립 합성 서버로 검증합니다. 운영자는 설치된 전체 도구와 OS 접근을 신뢰해야 합니다.

1.2 수용 검사는 독립 packed consumer·타입·107개 schema·실제 compiler/server adapter·과거 공개 archive 상호운용을 포함합니다. 워크플로 예제는 영속 복구와 명시적 재시도를 자동 replay와 구분합니다. 보안 감사·취약점 검증은 소유자의 보류 요청에 따라 계속 대기 중이며 DDS UI·Engine·Cloud scheduler·Marketplace·installer·보안 sandbox 수용 완료를 뜻하지 않습니다.

타입·API·한도와 전체 실행 예제

node node_modules/@altifigence/dds-plugin-sdk/examples/workflows/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/tool-streams-browser/serve.mjs

실제 adapter 예제에는 운영자가 승인한 기존 설치의 절대 경로를 추가합니다. 기본 예제는 SDK가 작성한 fixture만 사용하며 도구를 다운로드하지 않습니다.

node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs --typescript-root /absolute/path/to/typescript
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs --typescript-root /absolute/path/to/typescript --language-server-root /absolute/path/to/typescript-language-server