docs: define Inkspan modular acquisition architecture - #64
Conversation
|
Warning Review limit reached
Next review available in: 7 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughInkspan의 독립 제품 경계와 naruon 통합 계약을 문서화했다. 강한 ChangesInkspan 아키텍처 및 통합
Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
|
Exact-head review request for CI, Security Scan, and SAST Semgrep all succeeded on this exact head, and there are zero inline review threads. Please review the current head only; do not treat predecessor-head, queued, wrapper-only, or infrastructure-only evidence as approval. @opencode-agent review A qualifying non-author independent approval remains required; no reviewer identity, credential chain, or branch protection may be bypassed. |
|
|
|
@coderabbitai review |
|
|
@coderabbitai review Please review exact current head |
|
|
|
@coderabbitai review Independently review exact current head |
🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
base='66cf4b9e46b5cbbc936ba470da5d1e96ca1649af'
head='ae0debd4f3fd74f8e253df46b40d307154be76e3'
printf '%s\n' '== Checked-out HEAD =='
git rev-parse HEAD
printf '%s\n' '== Requested commits =='
git rev-parse "$base"
git rev-parse "$head"
printf '%s\n' '== Head parentage =='
git merge-base --is-ancestor "$base" "$head" && echo "base-is-ancestor=yes" || echo "base-is-ancestor=no"
printf '%s\n' '== Changed paths =='
git diff --name-status "$base" "$head"
printf '%s\n' '== Diff summary =='
git diff --stat "$base" "$head"
printf '%s\n' '== Documentation and test outlines =='
fd -t f -e md -e ts -e js . | rg '(^|/)(ARCHITECTURE\.md|naruon-compose-ui-panel\.md|naruon-modular-architecture\.md|CHANGELOG\.md)$|(?:test|spec|contract)'Length of output: 3800 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Exact range diff (no color) =='
git diff --no-ext-diff --unified=20 \
66cf4b9e46b5cbbc936ba470da5d1e96ca1649af \
ae0debd4f3fd74f8e253df46b40d307154be76e3 \
-- ARCHITECTURE.md CHANGELOG.md docs/doctoring/naruon-modular-architecture.md \
docs/naruon-compose-ui-panel.md src/architectureDocumentation.test.ts
printf '%s\n' '== Changed Markdown, numbered =='
for file in ARCHITECTURE.md CHANGELOG.md docs/doctoring/naruon-modular-architecture.md docs/naruon-compose-ui-panel.md; do
printf '\n===== %s =====\n' "$file"
cat -n "$file"
done
printf '%s\n' '== Documentation contract test, numbered =='
cat -n src/architectureDocumentation.test.ts
printf '%s\n' '== Autosave public exports and definitions =='
ast-grep outline src/autosave --items all --type function,class,interface,type --view expanded || true
rg -n -C 4 --glob '*.ts' \
'export\s+(?:\{[^}]*\}|(?:async\s+)?(?:function|class|const|type|interface)\s+)|\b(?:create|open|close|flush|dispose)[A-Z][A-Za-z0-9_]*\s*\(' \
src/autosave src/index.tsLength of output: 222679 🏁 Script executed: #!/bin/bash
set -euo pipefail
printf '%s\n' '== Editor handle declaration and evidence method =='
rg -n -C 8 --glob '*.ts' \
'interface\s+CwlEditorHandle\b|getDocumentEnvelopeRevisionEvidence\s*\(' \
src
printf '%s\n' '== Autosave session interface and close/resume behavior =='
sed -n '70,145p' src/autosave/session.ts
sed -n '308,410p' src/autosave/session.ts
printf '%s\n' '== Package subpath exports =='
fd -t f -a 'package.json' . -x sh -c '
printf "\n===== %s =====\n" "$1"
rg -n -C 12 "\"exports\"|autosave|styles" "$1"
' sh {}
printf '%s\n' '== Static documentation structure checks =='
python3 - <<'PY'
from pathlib import Path
import re
files = [
Path("ARCHITECTURE.md"),
Path("docs/naruon-compose-ui-panel.md"),
Path("docs/doctoring/naruon-modular-architecture.md"),
]
for path in files:
text = path.read_text(encoding="utf-8")
fences = re.findall(r"^```", text, flags=re.M)
print(f"{path}: fence_count={len(fences)} even={len(fences) % 2 == 0}")
for target in re.findall(r"\[[^\]]+\]\(([^)#]+)(?:#[^)]+)?\)", text):
resolved = (path.parent / target).resolve()
print(f" link={target} exists={resolved.exists()}")
PY
printf '%s\n' '== Exact range check after read-only inspection =='
git diff --check \
66cf4b9e46b5cbbc936ba470da5d1e96ca1649af \
ae0debd4f3fd74f8e253df46b40d307154be76e3
git status --shortLength of output: 16605
I found no actionable findings in the current-head changes. The documented integration matches the exported editor and autosave APIs. The keyed editing-context lifecycle, latest-generation capture guard, encoded document path segment, strong This review command does not submit an approval. Use the explicit ✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
docs/naruon-compose-ui-panel.md (1)
125-130: 🗄️ Data Integrity & Integration | 🔵 Trivial | 🏗️ Heavy lift충돌 복구 호출 경계를 예제에 연결하세요.
Line 125-130은conflict결과를saveMessage로만 표시합니다. 가이드의Line 242와CHANGELOG.mdLine 29는 복구된 strongETag를 session에 설치한 뒤 retained work를 재개해야 한다고 정의합니다. 그러나InkspanPanel은session.resume(...)을 호출할 callback이나 imperative handle을 노출하지 않습니다.onConflict/onRecovery계약 또는 완전한 복구 예제를 추가하여 host가 안전하게 재개할 수 있게 하세요.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/naruon-compose-ui-panel.md` around lines 125 - 130, The InkspanPanel conflict example only updates saveMessage for the conflict path, but it does not expose the recovery boundary needed by the documented session resume flow. Update the InkspanPanel example and its onConflict/onRecovery contract so the host can receive the recovered strong ETag and call session.resume(...) to continue retained work, using the existing InkspanPanel and session symbols rather than just displaying status text.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/doctoring/naruon-modular-architecture.md`:
- Around line 38-41: Remove the standalone blank blockquote marker between the
two quoted statements so they remain one continuous blockquote and markdownlint
rule MD028 passes. Update only the blockquote content around “Inkspan owns
editor and deterministic conversion surfaces.” and “Hosts own transport...”
In `@docs/naruon-compose-ui-panel.md`:
- Around line 67-83: Update the save callback example around async save(request)
and its fetch() call to either pass an AbortSignal/timeout via an
AbortController wrapper or clearly mark this snippet as non-production example
code. Keep the existing save/conflict handling path unchanged, and align the
documented behavior with the host-owned callback contract referenced by
save(request).
- Around line 140-142: Update the InkspanPanel heading and its aria-labelledby
reference to use an instance-unique ID instead of the shared
document-editor-title value, using React’s unique ID mechanism or an ID supplied
by the host. Keep each panel’s accessibility reference pointed to its own
Document editor heading.
In `@src/architectureDocumentation.test.ts`:
- Around line 58-101: Align the documentation contract tests with the guarantees
they claim to verify: in src/architectureDocumentation.test.ts lines 58-101,
strengthen the checks around the autosave and InkspanPanelSession examples to
validate fenced TSX structure and ordering, or rename and narrow the tests to
required marker checks; in docs/doctoring/naruon-modular-architecture.md lines
181-194, preserve the semantic lifecycle wording only if the tests are
strengthened, otherwise reduce the wording to required textual markers.
---
Nitpick comments:
In `@docs/naruon-compose-ui-panel.md`:
- Around line 125-130: The InkspanPanel conflict example only updates
saveMessage for the conflict path, but it does not expose the recovery boundary
needed by the documented session resume flow. Update the InkspanPanel example
and its onConflict/onRecovery contract so the host can receive the recovered
strong ETag and call session.resume(...) to continue retained work, using the
existing InkspanPanel and session symbols rather than just displaying status
text.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 534213d6-3be7-47b6-9d85-386d1ba359e2
📒 Files selected for processing (5)
ARCHITECTURE.mdCHANGELOG.mddocs/doctoring/naruon-modular-architecture.mddocs/naruon-compose-ui-panel.mdsrc/architectureDocumentation.test.ts
|
Exact-current-head review request for CI @coderabbitai review A qualifying non-author independent approval and every branch-protection gate remain mandatory. Do not approve, merge, update the branch, or modify reviewer identities from this request. |
|
I will use read-only review. I will not reuse predecessor-head, synthetic-merge, queued, pending, rate-limit, wrapper-only, or author-only evidence. I will not approve, merge, update the branch, or modify reviewer identities.
|
|
@coderabbitai review Please review exact current head |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
requested_head='2f8035079e87567e1788e8296101ae85ffbfbdd7'
repo='ContextualWisdomLab/inkspan'
pr_number='64'
echo '== Exact checkout verification =='
echo "checked_out=$(git rev-parse HEAD)"
echo "requested=$requested_head"
test "$(git rev-parse HEAD)" = "$requested_head"
echo '== Pull request metadata =='
gh pr view "$pr_number" --repo "$repo" --json number,baseRefOid,headRefOid,changedFiles,files \
--jq '{number, baseRefOid, headRefOid, changedFiles, files: [.files[].path]}'
base="$(gh pr view "$pr_number" --repo "$repo" --json baseRefOid --jq .baseRefOid)"
head="$(gh pr view "$pr_number" --repo "$repo" --json headRefOid --jq .headRefOid)"
test "$head" = "$requested_head"
git merge-base --is-ancestor "$base" "$head"
echo '== Exact range changed paths and summary =='
git diff --name-status "$base" "$head"
git diff --stat "$base" "$head"
git diff --check "$base" "$head"
echo '== Exact range diff =='
git diff --no-ext-diff --unified=30 "$base" "$head"
echo '== Changed-file outlines =='
git diff --name-only "$base" "$head" | while IFS= read -r file; do
printf '\n===== %s =====\n' "$file"
case "$file" in
*.ts|*.tsx|*.js|*.jsx)
ast-grep outline "$file" --items all --view expanded || true
;;
*)
cat -n "$file"
;;
esac
done
echo '== Relevant public source contracts =='
rg -n -C 8 --glob '*.{ts,tsx}' \
'CwlEditorHandle|InkspanPanelProps|createAutosave|AutosaveSession|StrongEntityTag|getDocumentEnvelopeRevisionEvidence|editingContextId|documentId' \
src
echo '== Markdown fence and local-link validation for changed Markdown =='
BASE="$base" HEAD="$head" python3 - <<'PY'
from pathlib import Path
import os, re, subprocess
changed = subprocess.check_output(
["git", "diff", "--name-only", os.environ["BASE"], os.environ["HEAD"]],
text=True,
).splitlines()
for name in changed:
path = Path(name)
if path.suffix.lower() != ".md":
continue
text = path.read_text(encoding="utf-8")
fences = len(re.findall(r"^```", text, flags=re.MULTILINE))
print(f"{name}: fences={fences}, balanced={fences % 2 == 0}")
for target in re.findall(r"\[[^\]]+\]\(([^)#]+)(?:#[^)]+)?\)", text):
if "://" in target or target.startswith("mailto:"):
continue
resolved = (path.parent / target).resolve()
print(f" local_link={target} exists={resolved.exists()}")
PY
echo '== Working-tree state =='
git status --shortLength of output: 179493 🏁 Script executed: #!/bin/bash
set -euo pipefail
requested_head='2f8035079e87567e1788e8296101ae85ffbfbdd7'
repo='ContextualWisdomLab/inkspan'
pr_number='64'
base="$(gh pr view "$pr_number" --repo "$repo" --json baseRefOid --jq .baseRefOid)"
head="$(gh pr view "$pr_number" --repo "$repo" --json headRefOid --jq .headRefOid)"
echo '== Prior verification summary =='
sed -n '1,180p' /tmp/coderabbit-shell-logs/shell-output-NP2Agk
echo '== Exact range metadata =='
printf 'base=%s\nhead=%s\n' "$base" "$head"
git diff --name-status "$base" "$head"
echo '== Exact range summary =='
git diff --stat "$base" "$head"
echo '== Commit sequence in exact range =='
git log --oneline --no-decorate "$base..$head"
echo '== Changed source and documentation files =='
git diff --name-only "$base" "$head" | while IFS= read -r file; do
printf '\n===== %s =====\n' "$file"
case "$file" in
*.md|*.ts|*.tsx) cat -n "$file" ;;
esac
done
echo '== Focused API declarations =='
sed -n '1,125p' src/autosave/session.ts
sed -n '299,410p' src/autosave/session.ts
sed -n '1,75p' src/documentRevisionEvidenceHandle.ts
sed -n '90,220p' src/types.ts
echo '== Documentation test implementation =='
cat -n src/architectureDocumentation.test.ts
echo '== Targeted documentation assertion check =='
python3 - <<'PY'
from pathlib import Path
guide = Path('docs/naruon-compose-ui-panel.md').read_text(encoding='utf-8')
for required in (
'createDocumentAutosaveSession',
'initialStrongEntityTag',
'ifMatchStrongEntityTag',
'nextStrongEntityTag',
'getDocumentEnvelopeRevisionEvidence',
'key={props.editingContextId}',
'encodeURIComponent(documentId)',
):
print(f'{required}: {required in guide}')
PYLength of output: 108033
I found no actionable findings in the exact current-head changes. The reviewed integration example matches the exported autosave and revision-evidence contracts. It uses a keyed editing context, lazy session state, encoded document paths, server-issued strong The Markdown fences and local links are valid. You are interacting with an AI system. |
|
@opencode-agent review Perform read-only independent review of exact current head |
1 participant
Purpose
Add one authoritative, buyer-reviewable architecture contract for Inkspan as both a standalone product and a modular CWL MSA component, with a concrete naruon
compose/ui.panelintegration guide.Bounded buyer-visible slice
ARCHITECTURE.mdwith text-reviewable deployment and optimistic-concurrency diagrams;ContextualWisdomLab/.github, naruon, contextual-orchestrator, host persistence, and host collaboration services;ETaghandoff, latest-generation capture ordering, bounded save transport, accessible conflict recovery, host-ownedY.Doclifecycle, and local-versus-shareable evidence;CHANGELOG.mdevidence.Architecture boundary
Inkspan owns editor and deterministic conversion surfaces. Hosts own transport, authorization, tenant isolation, persistence, credentials, migration, retention, and model-use policy.
This PR adds no naruon runtime dependency, persistence adapter, provider SDK, credential path, database object, model route, workflow permission, package version, or publication.
Test-first review repair
CodeRabbit's current actionable findings were validated and repaired test-first:
AbortSignalto every example save request and documented ambiguous timeout semantics;useId();session.resume(...).The documentation contract was added red before the guide changes. The doctoring record and changelog now describe the exact bounded transport, recovery, accessibility, and verification guarantees. CodeRabbit automatically marked all four inline threads addressed. No transient or write-capable repair workflow was created or retained.
Standards and claim boundary
The doctoring record cites RFC 9110, WCAG 2.2, NIST SP 800-204, NIST SP 800-204D, OWASP ASVS 5.0.0, React primary documentation, and current Next.js App Router guidance in APA 7 format. These sources inform the design and verification plan; this documentation does not claim deployed-system conformance by itself.
Exact-head evidence
Current exact head:
2f8035079e87567e1788e8296101ae85ffbfbdd7.Successful on this exact head:
31028648883: TypeScript typecheck, repository tests with 100% production coverage, library build, packed-package consumers, demo build, and Office Python 3.11/3.14 docstring, branch-coverage, wheel, schema, and license gates;31028648930;31028648859; andRemaining merge gates
Do not merge until all repository policy gates are satisfied. The current incremental CodeRabbit pass was externally rate-limited after validating the changed-file set, so a current-head full review remains required when capacity becomes available. A qualifying non-author independent approval and any applicable OpenCode, Noema, Strix, GitHub Advanced Security, Dependabot, or other required policy evidence also remain required.
Queued, pending, skipped-required, predecessor-head, author-only, or local-only evidence is not treated as success, and protections must not be bypassed.